The cl-stopwatch Reference Manual

Table of Contents

The cl-stopwatch Reference Manual

This is the cl-stopwatch Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:50:47 2020 GMT+0.

1 Introduction

=== SOME DOCUMENTATION TO CL-STOPWATCH ===

Copyright (c) 2012 Robert Smith

See LICENSE for license details.


== To Time Something ==

Use WITH-STOPWATCH to time something in milliseconds. For example:

> (with-stopwatch
>   (sleep 5)
>   'lol)

which results in two values, the first is the result of the
computation, the second is the number of milliseconds it took to
compute, as shown:

> LOL
> 5010

If your code isn't simple enough to wrap with a WITH-STOPWATCH, you
can use the lower level stopwatch functions. The following example
should be self-explanatory.

> * (stopwatch-start :race)
> ; No value
> * (stopwatch-read :race)
> 10414
> * (stopwatch-read :race)
> 17387
> * (stopwatch-reset :race)
> ;; No Value
> * (stopwatch-read :race)
> 5507
> * (stopwatch-stop :race)
> 22128


== To Indicate Progress ==

Use PROGRESS-TASK to indicate progress to a stream. Example:

> (progress-task :sleepy-time "Waiting to wake up"
>   (sleep 5)
>   (format t "just 5 more seconds...~%")
>   (progress-task :snooze "Snoozing a little more"
>     (sleep 5))
>   'ok-im-awake)

which results in the following getting output.

> ;;;  SLEEPY-TIME: Waiting to wake up...
> just 5 more seconds...
> ;;;    SNOOZE: Snoozing a little more...
> ;;;    SNOOZE: Done. [4999.0 ms]
> ;;;  SLEEPY-TIME: Done. [10017.0 ms]
> OK-IM-AWAKE

Note the nesting, and the increased indentation as a result.

There are analogous functions for doing "progress tasks" at a low
level like the stopwatch functions. For example:

> (progn
>   (progress-task-start :nap "Taking a nap")
>   (sleep 3)
>   (progress-task-done :nap))

which results in:

> ;;;  NAP: Taking a nap...
> ;;;  NAP: Done. [3000.0 ms]
> ; No value


== To Time a Compiled Form ==

Suppose you have some code you want to benchmark, but you wish to
benchmark it compiled. To guarantee it gets compiled, use TIME*.

For example:

> (time* (progn
>          (sleep 5)
>          'done))

which outputs

> Evaluation took:
>   5.0000 seconds of real time
>   0.000045 seconds of total run time (0.000025 user, 0.000020 system)
>   0.00% CPU
>   0 bytes consed
>   
> DONE

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-stopwatch

Author

Robert Smith

License

BSD 3-clause. See LICENSE.

Description

Timing and clocking in Common Lisp.

Version

0.1

Source

cl-stopwatch.asd (file)

Components

• package.lisp (file)
• stopwatch.lisp (file)
• progress.lisp (file)
• time.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-stopwatch.asd

Location

cl-stopwatch.asd

Systems

cl-stopwatch (system)

Packages

cl-stopwatch-asd

3.1.2 cl-stopwatch/package.lisp

Parent

cl-stopwatch (system)

Location

package.lisp

Packages

cl-stopwatch

3.1.3 cl-stopwatch/stopwatch.lisp

Dependency

package.lisp (file)

Parent

cl-stopwatch (system)

Location

stopwatch.lisp

Exported Definitions

• stopwatch-read (function)
• stopwatch-reset (function)
• stopwatch-start (function)
• stopwatch-stop (function)
• with-stopwatch (macro)

Internal Definitions

• *stopwatch-timing* (special variable)
• get-accurate-time (macro)

3.1.4 cl-stopwatch/progress.lisp

Dependency

stopwatch.lisp (file)

Parent

cl-stopwatch (system)

Location

progress.lisp

Exported Definitions

• progress-task (macro)
• progress-task-done (function)
• progress-task-start (function)

Internal Definitions

*progress-indent* (special variable)

3.1.5 cl-stopwatch/time.lisp

Dependency

progress.lisp (file)

Parent

cl-stopwatch (system)

Location

time.lisp

Exported Definitions

time* (macro)

4 Packages

Packages are listed by definition order.

4.1 cl-stopwatch-asd

Source

cl-stopwatch.asd

Use List

• asdf/interface
• common-lisp

4.2 cl-stopwatch

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• progress-task (macro)
• progress-task-done (function)
• progress-task-start (function)
• stopwatch-read (function)
• stopwatch-reset (function)
• stopwatch-start (function)
• stopwatch-stop (function)
• time* (macro)
• with-stopwatch (macro)

Internal Definitions

• *progress-indent* (special variable)
• *stopwatch-timing* (special variable)
• get-accurate-time (macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Macros

Macro: progress-task KW STRING &body BODY

Execute BODY, reporting the task, labeled by the keyword KW and commented with STRING. Report its end time and return the value returned by BODY.

Package

cl-stopwatch

Source

progress.lisp (file)

Macro: time* FORM

Freshly compile FORM and time its execution.

Package

cl-stopwatch

Source

time.lisp (file)

Macro: with-stopwatch &body BODY

Execute BODY, returning its value as well as the value of the watch.

Package

cl-stopwatch

Source

stopwatch.lisp (file)

5.1.2 Functions

Function: progress-task-done KW &optional STREAM

End the task designated by the keyword KW and report its completion time to STREAM.

Package

cl-stopwatch

Source

progress.lisp (file)

Function: progress-task-start KW STRING &optional STREAM

Start a task designated by the keyword KW, with a comment STRING, and print an indication that the task has started and start a stopwatch. Print everything to STREAM.

Package

cl-stopwatch

Source

progress.lisp (file)

Function: stopwatch-read KW

Read a stopwatch designated by KW.

Package

cl-stopwatch

Source

stopwatch.lisp (file)

Function: stopwatch-reset KW

Resets the stopwatch designated by KW. Equivalent to starting it.

Package

cl-stopwatch

Source

stopwatch.lisp (file)

Function: stopwatch-start KW

Start a stopwatch designated by KW.

Package

cl-stopwatch

Source

stopwatch.lisp (file)

Function: stopwatch-stop KW

Stop the stopwatch designated by KW and return the reading in milliseconds.

Package

cl-stopwatch

Source

stopwatch.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *progress-indent*

Package

cl-stopwatch

Source

progress.lisp (file)

Special Variable: *stopwatch-timing*

Package

cl-stopwatch

Source

stopwatch.lisp (file)

5.2.2 Macros

Macro: get-accurate-time ()

Get the time in milliseconds, accurately.

Package

cl-stopwatch

Source

stopwatch.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types