15.6 Machine Time

The previous section dealt with procedures that manipulate clock time. This section describes procedures that deal with computer time: elapsed CPU time, elapsed real time, and so forth. These procedures are useful for measuring the amount of time it takes to execute code.

Some of the procedures in this section manipulate a time representation called ticks. A tick is a unit of time that is unspecified here but can be converted to and from seconds by supplied procedures. A count in ticks is represented as an exact integer. At present each tick is one millisecond, but this may change in the future.

procedure: process-time-clock

Returns the amount of process time, in ticks, that has elapsed since Scheme was started. Process time is measured by the operating system and is time during which the Scheme process is computing. It does not include time in system calls, but depending on the operating system it may include time used by subprocesses.

(process-time-clock) ⇒ 21290

procedure: real-time-clock

Returns the amount of real time, in ticks, that has elapsed since Scheme was started. Real time is the time measured by an ordinary clock.

(real-time-clock) ⇒ 33474836

procedure: internal-time/ticks->seconds ticks

Returns the number of seconds corresponding to ticks. The result is always a real number.

(internal-time/ticks->seconds 21290) ⇒ 21.29
(internal-time/ticks->seconds 33474836) ⇒ 33474.836

procedure: internal-time/seconds->ticks seconds

Returns the number of ticks corresponding to seconds. Seconds must be a real number.

(internal-time/seconds->ticks 20.88) ⇒ 20880
(internal-time/seconds->ticks 20.83) ⇒ 20830

procedure: system-clock

Returns the amount of process time, in seconds, that has elapsed since Scheme was started. Roughly equivalent to:

(internal-time/ticks->seconds (process-time-clock))

Example:

(system-clock) ⇒ 20.88

procedure: runtime

Returns the amount of process time, in seconds, that has elapsed since Scheme was started. However, it does not include time spent in garbage collection.

(runtime) ⇒ 20.83

procedure: with-timings thunk receiver

Calls thunk with no arguments. After thunk returns, receiver is called with three arguments describing the time spent while computing thunk: the elapsed run time, the amount of time spent in the garbage collector, and the elapsed real time. All three times are in ticks.

This procedure is most useful for doing performance measurements, and is designed to have relatively low overhead.

(with-timings
 (lambda () … hairy computation …)
 (lambda (run-time gc-time real-time)
   (write (internal-time/ticks->seconds run-time))
   (write-char #\space)
   (write (internal-time/ticks->seconds gc-time))
   (write-char #\space)
   (write (internal-time/ticks->seconds real-time))
   (newline)))

procedure: measure-interval runtime? procedure

Calls procedure, passing it the current process time, in seconds, as an argument. The result of this call must be another procedure. When procedure returns, the resulting procedure is tail-recursively called with the ending time, in seconds, as an argument.

If runtime? is #f, the elapsed time is deducted from the elapsed system time returned by runtime.

While this procedure can be used for time measurement, its interface is somewhat clumsy for that purpose. We recommend that you use with-timings instead, because it is more convenient and has lower overhead.

(measure-interval #t
                  (lambda (start-time)
                    (let ((v … hairy computation …))
                      (lambda (end-time)
                        (write (- end-time start-time))
                        (newline)
                        v))))