6.40 Timing

This section describes some of Vicare’s timing facilities which may be useful for benchmarking and performance tuning.

Syntax: time expression

The time macro performs the following: it evaluates expression, then prints a summary of the run time statistics, then returns the values returned by expression. The run–time summary includes the number of bytes allocated, the number of garbage collection runs, and the time spent in both the mutator and the collector.

> (let ()                                   ;;; 10 million
    (define ls (time (vector->list (make-vector 10000000))))
    (time (append ls ls))
    (values))
running stats for (vector->list (make-vector 10000000)):
    3 collections
    672 ms elapsed cpu time, including 547 ms collecting
    674 ms elapsed real time, including 549 ms collecting
    120012328 bytes allocated
running stats for (append ls ls):
    4 collections
    1536 ms elapsed cpu time, including 1336 ms collecting
    1538 ms elapsed real time, including 1337 ms collecting
    160000040 bytes allocated

Note: The output listed above is just a sample that was taken at some point on some machine. The output on your machine at the time you read this may vary.

Function: Procedure time-it thunk

Function: Procedure time-it message thunk

The procedure time-it takes a datum denoting the name of the computation and a thunk (i.e. a procedure with no arguments), invokes the thunk, prints the stats, and returns the values obtained from invoking the thunk. If the value of message is true, message is used when displaying the run–time statistics; if the value of message is #f, then no name for the computation is displayed; when not given message defaults to #f.

> (time-it "a very fast computation"
    (lambda () (values 1 2 3)))
running stats for a very fast computation:
    no collections
    0 ms elapsed cpu time, including 0 ms collecting
    0 ms elapsed real time, including 0 ms collecting
    24 bytes allocated
1
2
3

> (time-it #f (lambda () 12))
running stats:
    no collections
    0 ms elapsed cpu time, including 0 ms collecting
    0 ms elapsed real time, including 0 ms collecting
    0 bytes allocated
12

Function: time-and-gather gather thunk

Like time-it evaluate the procedure thunk timing its execution; return the return values of thunk. Build two objects of type <stats> and apply the procedure gather to them: the first represents the statistics before thunk evaluation, the second represents the statistics after thunk evaluation.

Parameter: verbose-timer

When set to non–false: print more informations as result of time-it and time-and-gather.

Object Type: <stats>

Type name identifier for disjoint objects representing evaluation statistics. It has the following fields:

user-secs

The user seconds.

user-usecs

The user microseconds.

sys-secs

The system seconds.

sys-usecs

The system microseconds.

real-secs

The real seconds.

real-usecs

The real microseconds.

collection-id

The garbage collection identifier.

gc-user-secs

The garbage collection user seconds.

gc-user-usecs

The garbage collection user microseconds.

gc-sys-secs

The garbage collection system seconds.

gc-sys-usecs

The garbage collection system microseconds.

gc-real-secs

The garbage collection real seconds.

gc-real-usecs

The garbage collection real microseconds.

bytes-minor

The garbage collection bytes minor.

bytes-major

The garbage collection bytes major.

Function: stats? obj

Return true if obj is an object of type <stats>.

Function: stats-user-secs stats

Return the user seconds field of stats.

Function: stats-user-usecs stats

Return the user microseconds field of stats.

Function: stats-sys-secs stats

Return the system seconds field of stats.

Function: stats-sys-usecs stats

Return the system microseconds field of stats.

Function: stats-real-secs stats

Return the real seconds field of stats.

Function: stats-real-usecs stats

Return the real microseconds field of stats.

Function: stats-collection-id stats

Return the collection identifier field of stats.

Function: stats-gc-user-secs stats

Return the garbage collection user seconds field of stats.

Function: stats-gc-user-usecs stats

Return the garbage collection user microseconds field of stats.

Function: stats-gc-sys-secs stats

Return the garbage collection system seconds field of stats.

Function: stats-gc-sys-usecs stats

Return the garbage collection system microseconds field of stats.

Function: stats-gc-real-secs stats

Return the garbage collection real seconds field of stats.

Function: stats-gc-real-usecs stats

Return the garbage collection real microseconds field of stats.

Function: stats-bytes-minor stats

Return the garbage collection bytes minor field of stats.

Function: stats-bytes-major stats

Return the garbage collection bytes major field of stats.