Atomichron

8.16

Atomichron🔗ℹ

Atomichron is a microbenchmarking library. A microbenchmark is an experiment that measures the performance of a very small and isolated piece of code. Microbenchmarks are best used to test the performance of library code, not real world code — the performance of real world code is determined by complex environmental factors and variables that a microbenchmark cannot reproduce. Library code has to perform well in many different environments so these environmental factors can usually be ignored.

As a general rule of thumb, never write a microbenchmark to measure code that performs IO. This includes code that reads or writes files and code that talks to other computers over the network. The performance of such operations cannot be reliably reproduced or measured by Atomichron.

procedure
(microbenchmark? v) → boolean?
v : any/c

A predicate for microbenchmarks.

procedure
(make-microbenchmark
#:iterations num-iterations
#:microexpression-iterations num-microexpression-iterations
#:microexpression-builder builder
[ #:name name])
→ microbenchmark?
  num-iterations : exact-positive-integer?
  num-microexpression-iterations : exact-positive-integer?
  builder : (-> natural? microexpression?)
  name : (or/c interned-symbol? #f) = #f

Constructs a microbenchmark named name. Running the microbenchmark will construct num-iterations different microexpressions using the builder function. Then each microexpression is run num-microexpression-iterations times and the total time for that microexpression is recorded. Microexpressions are run multiple times because for many microexpressions, a single run would take so little time that it would be difficult to accurately measure.

Examples:

> (define num-iterations 100)
> (define size 1000)
> (define vec (build-vector size values))
> (define indices (build-vector num-iterations (λ (_) (random size))))
> (define vector-ref-benchmark
    (make-microbenchmark
     #:name 'vector-ref-benchmark
     #:iterations num-iterations
     #:microexpression-iterations 1000
     #:microexpression-builder
     (λ (iteration)
       (define i (vector-ref indices iteration))
       (make-microexpression #:thunk (λ () (vector-ref vec i))))))
> (microbenchmark-run! vector-ref-benchmark)
(microbenchmark-result
  #:average-cpu-nanoseconds 10
  #:average-gc-cpu-nanoseconds 0
  #:average-real-nanoseconds 0
  #:benchmark-name 'vector-ref-benchmark)

procedure
(microbenchmark-run! benchmark) → microbenchmark-result?
benchmark : microbenchmark?

Runs benchmark and returns timing results.

procedure
(microbenchmark-result? v) → boolean?
v : any/c

A predicate for microbenchmark results returned from microbenchmark-run!.

procedure
(microbenchmark-result #:benchmark-name name
#:average-cpu-nanoseconds cpu-nanos
#:average-real-nanoseconds real-nanos
#:average-gc-cpu-nanoseconds gc-nanos)
→ microbenchmark-result?
  name : (or/c interned-symbol? #f)
  cpu-nanos : (and/c rational? (not/c negative?))
  real-nanos : (and/c rational? (not/c negative?))
  gc-nanos : (and/c rational? (not/c negative?))

Constructs a microbenchmark result. This function is normally not called by users. Instead results are retrieved from microbenchmark-run!. See time-apply for an explanation of the differences between CPU time, real time, and GC CPU time.

procedure
(microbenchmark-result-benchmark-name result)
→ (or/c interned-symbol? #f)
result : microbenchmark-result?

Returns the name of the microbenchmark that result is for.

procedure
(microbenchmark-result-average-cpu-nanoseconds result)
→ (and/c rational? (not/c negative?))
result : microbenchmark-result?

Returns the average number of nanoseconds of CPU processing time spent in evaluating a microexpression once.

procedure
(microbenchmark-result-average-real-nanoseconds result)
→ (and/c rational? (not/c negative?))
result : microbenchmark-result?

Returns the average number of nanoseconds of real time that elapsed while evaluating a microexpression once.

procedure
(microbenchmark-result-average-gc-cpu-nanoseconds result)
→ (and/c rational? (not/c negative?))
result : microbenchmark-result?

Returns the averages number of nanoseconds of CPU processing time spent on garbage collection while evaluating a microexpression once. This time is included in microbenchmark-result-average-cpu-nanoseconds.

procedure
(microexpression? v) → boolean?
v : any/c

A predicate for microexpressions.

procedure
(make-microexpression #:thunk thunk
[ #:name name]) → microexpression?
thunk : (-> any/c any)
name : (or/c interned-symbol? #f) = #f

Constructs a microexpression, which is a small and simple expression that is timed and executed repeatedly during a microbenchmark. Running the constructed microexpression calls thunk. See make-microbenchmark for an example of how microbenchmarks construct microexpressions.