(std stopwatch)

Reference

Overview

Stopwatches reading ambient monotonic time, and time-it benchmarking utility.

(import (std stopwatch))

(def sw (stopwatch))
(stopwatch-start! sw)
(do-the-work)
(stopwatch-stop! sw)
(stopwatch-ms sw)          ; elapsed milliseconds, as a long
(stopwatch-ns sw)          ; elapsed nanoseconds
(ref sw 's)                ; elapsed time in whole seconds
(ns->string (stopwatch-ns sw))   ; e.g. "12.5 us"

(time-it #:times 10 (do-the-work))

A stopwatch reads monotonic time from the prelude’s monotonic-ns, which queries current-clock. It does not wrap System.Diagnostics.Stopwatch. This allows tests to bind a deterministic virtual clock and produce predictable timings:

(parameterize ((current-clock (make-clock #:monotonic-ms (fun () 0L))))
  (time-the-thing))   ; every stopwatch inside reads 0

Stopwatches are mutable structures. They can be started and stopped repeatedly, accumulating elapsed runtime across active periods in nanoseconds, at the resolution the clock has. The other units are read from the nanoseconds and rounded down.

Stopwatches implement Refable using symbol units: (ref sw 'ns), 'us, 'ms and 's return elapsed time in that unit, rounded down. Any other symbol raises System.ArgumentException.

See also: Stopwatch, stopwatch, time-it

Reference

Types

Functions

Macros

Types

Stopwatch

record ↑ Types

Stopwatch structure tracking total elapsed time and active run state.

started
Timestamp in nanoseconds of the current active run, or -1 if stopped.
elapsed
Accumulated nanoseconds across completed runs.

Both fields are mutable to support in-place updates. Use this module’s API rather than record-set! directly.

(ref sw 'ns), 'us, 'ms and 's read elapsed time in that unit. Any other symbol raises System.ArgumentException.

See also: stopwatch, stopwatch-start!, stopwatch-ns, stopwatch-ms

Functions

stopwatch

function ↑ Functions

(: stopwatch (-> Stopwatch))
(stopwatch)

Creates a new stopped stopwatch initialized to zero.

returns
A stopped stopwatch with nothing elapsed.

See also: stopwatch-start!

stopwatch-start!

function ↑ Functions

(: stopwatch-start! (-> Stopwatch void))
(stopwatch-start! sw)

Starts or resumes a stopwatch.

sw
The stopwatch.

Starting an already-running stopwatch has no effect.

See also: stopwatch-stop!, stopwatch-ms

stopwatch-stop!

function ↑ Functions

(: stopwatch-stop! (-> Stopwatch void))
(stopwatch-stop! sw)

Stops a stopwatch and accumulates the current run duration.

sw
The stopwatch. Stopping an already-stopped stopwatch has no effect.

See also: stopwatch-start!, stopwatch-ms

stopwatch-ns

function ↑ Functions

(: stopwatch-ns (-> Stopwatch long))
(stopwatch-ns sw)

Returns total elapsed nanoseconds for a stopwatch.

sw
The stopwatch.
returns
Total elapsed time across completed runs, plus the active run if currently running.

Can be called on running stopwatches without interrupting timing. The resolution is the clock’s: on system-clock, that of System.Diagnostics.Stopwatch.

See also: stopwatch-stop!, stopwatch-us, stopwatch-ms, ns->string

stopwatch-us

function ↑ Functions

(: stopwatch-us (-> Stopwatch long))
(stopwatch-us sw)

Returns total elapsed microseconds for a stopwatch, rounded down.

sw
The stopwatch.
returns
What stopwatch-ns returns, divided by 1000.

See also: stopwatch-ns

stopwatch-ms

function ↑ Functions

(: stopwatch-ms (-> Stopwatch long))
(stopwatch-ms sw)

Returns total elapsed milliseconds for a stopwatch, rounded down.

sw
The stopwatch.
returns
Total elapsed time across completed runs, plus the active run if currently running.

Can be called on running stopwatches without interrupting timing.

See also: stopwatch-stop!, stopwatch-ns

ns->string

function ↑ Functions

(: ns->string (-> long string))
(ns->string ns)

A duration in nanoseconds as text, in a unit that fits it.

ns
The duration, in nanoseconds.
returns
The duration in ns, us, ms or s: the largest unit it is at least 1 of, with one decimal under 100.
(ns->string 850L)        ; "850 ns"
(ns->string 12500L)      ; "12.5 us"
(ns->string 3210000L)    ; "3.2 ms"

See also: stopwatch-ns, time-it

get-memory-usage

function ↑ Functions

Returns bytes allocated on the current thread since creation.

returns
A monotonically increasing long. Subtract consecutive readings to measure allocations.

Delegates to System.GC.GetAllocatedBytesForCurrentThread. Measures allocations on the calling thread only; allocations on other threads or fibers are not included.

See also: time-it

Macros

time-it

macro ↑ Macros

(time-it body ...)
(time-it #:times n body ...)
(time-it #:warm-up-rounds w body ...)
(time-it #:times n #:warm-up-rounds w body ...)

Measures a body and prints one line: (std bench)’s time-it, which this module has too.

n
With #:times, exactly n timed runs: no calibration.
w
With #:warm-up-rounds, exactly w untimed runs first. 0 unless given.
body ...
The forms, run as one call; the value of the last is kept alive.
(time-it (list-sort big-list))
;; (list-sort big-list): 8.31 ms ± 1.1% (min 8.12 ms), 2.40 MB/call, 120 samples

The same macro as (std bench)’s time-it, which documents it in full: a body measured as a benchmark is, warmed up, calibrated and sampled, or run once when its first run takes more than a second. It is here so that an (import (std stopwatch)) that used it goes on working.

See also: stopwatch