The cl-stopwatch Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-stopwatch Reference Manual

This is the cl-stopwatch Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:34:10 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

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



Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

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

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-stopwatch.asd

Location

cl-stopwatch.asd

Systems

cl-stopwatch (system)

Packages

cl-stopwatch-asd


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-stopwatch/package.lisp

Parent

cl-stopwatch (system)

Location

package.lisp

Packages

cl-stopwatch


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-stopwatch/stopwatch.lisp

Dependency

package.lisp (file)

Parent

cl-stopwatch (system)

Location

stopwatch.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-stopwatch/progress.lisp

Dependency

stopwatch.lisp (file)

Parent

cl-stopwatch (system)

Location

progress.lisp

Exported Definitions
Internal Definitions

*progress-indent* (special variable)


Previous: , Up: Lisp files   [Contents][Index]

3.1.5 cl-stopwatch/time.lisp

Dependency

progress.lisp (file)

Parent

cl-stopwatch (system)

Location

time.lisp

Exported Definitions

time* (macro)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 cl-stopwatch-asd

Source

cl-stopwatch.asd

Use List

Previous: , Up: Packages   [Contents][Index]

4.2 cl-stopwatch

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: get-accurate-time ()

Get the time in milliseconds, accurately.

Package

cl-stopwatch

Source

stopwatch.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-stopwatch.asd: The cl-stopwatch<dot>asd file
cl-stopwatch/package.lisp: The cl-stopwatch/package<dot>lisp file
cl-stopwatch/progress.lisp: The cl-stopwatch/progress<dot>lisp file
cl-stopwatch/stopwatch.lisp: The cl-stopwatch/stopwatch<dot>lisp file
cl-stopwatch/time.lisp: The cl-stopwatch/time<dot>lisp file

F
File, Lisp, cl-stopwatch.asd: The cl-stopwatch<dot>asd file
File, Lisp, cl-stopwatch/package.lisp: The cl-stopwatch/package<dot>lisp file
File, Lisp, cl-stopwatch/progress.lisp: The cl-stopwatch/progress<dot>lisp file
File, Lisp, cl-stopwatch/stopwatch.lisp: The cl-stopwatch/stopwatch<dot>lisp file
File, Lisp, cl-stopwatch/time.lisp: The cl-stopwatch/time<dot>lisp file

L
Lisp File, cl-stopwatch.asd: The cl-stopwatch<dot>asd file
Lisp File, cl-stopwatch/package.lisp: The cl-stopwatch/package<dot>lisp file
Lisp File, cl-stopwatch/progress.lisp: The cl-stopwatch/progress<dot>lisp file
Lisp File, cl-stopwatch/stopwatch.lisp: The cl-stopwatch/stopwatch<dot>lisp file
Lisp File, cl-stopwatch/time.lisp: The cl-stopwatch/time<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   F   G   M   P   S   T   W  
Index Entry  Section

F
Function, progress-task-done: Exported functions
Function, progress-task-start: Exported functions
Function, stopwatch-read: Exported functions
Function, stopwatch-reset: Exported functions
Function, stopwatch-start: Exported functions
Function, stopwatch-stop: Exported functions

G
get-accurate-time: Internal macros

M
Macro, get-accurate-time: Internal macros
Macro, progress-task: Exported macros
Macro, time*: Exported macros
Macro, with-stopwatch: Exported macros

P
progress-task: Exported macros
progress-task-done: Exported functions
progress-task-start: Exported functions

S
stopwatch-read: Exported functions
stopwatch-reset: Exported functions
stopwatch-start: Exported functions
stopwatch-stop: Exported functions

T
time*: Exported macros

W
with-stopwatch: Exported macros

Jump to:   F   G   M   P   S   T   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*progress-indent*: Internal special variables
*stopwatch-timing*: Internal special variables

S
Special Variable, *progress-indent*: Internal special variables
Special Variable, *stopwatch-timing*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-stopwatch: The cl-stopwatch system
cl-stopwatch: The cl-stopwatch package
cl-stopwatch-asd: The cl-stopwatch-asd package

P
Package, cl-stopwatch: The cl-stopwatch package
Package, cl-stopwatch-asd: The cl-stopwatch-asd package

S
System, cl-stopwatch: The cl-stopwatch system

Jump to:   C   P   S