[[LarcenyBenchmarkingSection]]

Benchmarking
~~~~~~~~~~~~

The `(larceny benchmarking)` library exports the
`time` syntax and `run-benchmark` procedure described
below.

_Syntax time_

++(time expression)++

Evaluates _expression_ and returns its result
after printing approximations to the storage
allocated and time taken during evaluation of
_expression_.

----------------------------------------------------------------
    > (import (larceny benchmarking))

    > (time (features))        ; finds and reads all available libraries
    Words allocated: 20969536
    Elapsed time...: 286 ms (User: 276 ms; System: 9 ms)
    Elapsed GC time: 5 ms (CPU: 6 in 20 collections (20 minor).)
    (r7rs r6rs 
          larceny
          larceny-1.3
          [lists 400+ libraries])

    > (time (features))        ; faster because the result was cached
    Words allocated: 0
    Elapsed time...: 1 ms (User: 1 ms; System: 0 ms)
    Elapsed GC time: 0 ms (CPU: 0 in 0 collections (0 minor).)
----------------------------------------------------------------

proc:run-benchmark[args="name iterations thunk predicate"]

Given the _name_ of a benchmark, the number of
_iterations_ to be performed, a zero-argument
procedure _thunk_ that runs the benchmark,
and a unary _predicate_ that checks the result
of _thunk_, prints approximations to the storage
allocated and time taken by _iterations_ calls
to _thunk_.

----------------------------------------------------------------
    > (run-benchmark "fib 30"
                     1000
                     (lambda () (fib 30))
                     (lambda (x) (= x 832040)))

    fib 30
    Words allocated: 0
    Elapsed time...: 11261 ms (User: 11255 ms; System: 0 ms)
    Elapsed GC time: 0 ms (CPU: 0 in 0 collections (0 minor).)
----------------------------------------------------------------
