The the-cost-of-nothing Reference Manual

4.1.1 the-cost-of-nothing/the-cost-of-nothing.asd

Source

the-cost-of-nothing.asd.

Parent Component

the-cost-of-nothing (system).

ASDF Systems

the-cost-of-nothing.

---

4.1.2 the-cost-of-nothing/core/packages.lisp

Source

the-cost-of-nothing.asd.

Parent Component

core (module).

Packages

the-cost-of-nothing.

---

4.1.3 the-cost-of-nothing/core/utilities.lisp

Dependency

packages.lisp (file).

Source

the-cost-of-nothing.asd.

Parent Component

core (module).

Public Interface

• print-time (function).
• write-si-unit (function).

Internals

• *si-prefix-alist* (special variable).
• call-with-memoization (function).
• compiled-lambda (function).
• define-memo-function (macro).
• lambda-list-bindings (function).
• make-argument-list (function).
• make-lambda-list (function).
• nth-keyword-name (function).
• with-memoization (macro).

---

4.1.4 the-cost-of-nothing/core/timestamps.lisp

Dependency

utilities.lisp (file).

Source

the-cost-of-nothing.asd.

Parent Component

core (module).

Internals

• *timestamp-function* (special variable).
• call-with-fuzzy-timestamps (function).
• make-timestamp (function).
• with-fuzzy-timestamps (macro).

---

4.1.5 the-cost-of-nothing/core/monitoring.lisp

Dependency

timestamps.lisp (file).

Source

the-cost-of-nothing.asd.

Parent Component

core (module).

Public Interface

• make-measurement (function).
• measurement (structure).
• measurement-context (reader).
• (setf measurement-context) (writer).
• measurement-name (reader).
• (setf measurement-name) (writer).
• measurement-timestamp (reader).
• (setf measurement-timestamp) (writer).
• measurement-value (reader).
• (setf measurement-value) (writer).
• measurementp (function).
• monitor (macro).
• monitoring-region-end (structure).
• monitoring-region-start (structure).
• print-object (method).
• print-object (method).
• print-object (method).
• with-monitoring-region (macro).

Internals

• %monitor (function).
• *context* (special variable).
• *measurements* (special variable).
• call-with-monitoring-region (function).
• copy-measurement (function).
• copy-monitoring-region-end (function).
• copy-monitoring-region-start (function).
• make-monitoring-region-end (function).
• make-monitoring-region-start (function).
• monitoring-region-end-context (function).
• (setf monitoring-region-end-context) (function).
• monitoring-region-end-name (function).
• (setf monitoring-region-end-name) (function).
• monitoring-region-end-p (function).
• monitoring-region-end-timestamp (function).
• (setf monitoring-region-end-timestamp) (function).
• monitoring-region-end-value (function).
• (setf monitoring-region-end-value) (function).
• monitoring-region-start-context (function).
• (setf monitoring-region-start-context) (function).
• monitoring-region-start-name (function).
• (setf monitoring-region-start-name) (function).
• monitoring-region-start-p (function).
• monitoring-region-start-timestamp (function).
• (setf monitoring-region-start-timestamp) (function).
• monitoring-region-start-value (function).
• (setf monitoring-region-start-value) (function).
• store-measurement (generic function).

---

4.1.6 the-cost-of-nothing/core/benchmarking.lisp

Dependency

monitoring.lisp (file).

Source

the-cost-of-nothing.asd.

Parent Component

core (module).

Public Interface

• bench (macro).
• benchmark (macro).
• benchmark-thunk (function).
• touch (function).

Internals

• *default-min-sample-time* (special variable).
• *default-overhead* (special variable).
• execution-time-of-thunk (function).
• sample-execution-time-of-thunk (function).

---

4.1.7 the-cost-of-nothing/core/time-series.lisp

Dependency

benchmarking.lisp (file).

Source

the-cost-of-nothing.asd.

Parent Component

core (module).

Internals

• measurements (reader method).
• (setf measurements) (writer method).
• time-series (class).

---

4.1.8 the-cost-of-nothing/benchmarks/memory-management.lisp

Source

the-cost-of-nothing.asd.

Parent Component

benchmarks (module).

Public Interface

• cons-cost (function).
• gc-cost (function).
• make-list-cost (function).
• make-sequence-cost (function).

Internals

• make-instance-cost (function).
• make-struct-cost (function).
• print-memory-management-report (function).

---

4.1.9 the-cost-of-nothing/benchmarks/functions.lisp

Dependency

memory-management.lisp (file).

Source

the-cost-of-nothing.asd.

Parent Component

benchmarks (module).

Public Interface

funcall-cost (function).

Internals

print-functions-report (function).

---

4.1.10 the-cost-of-nothing/benchmarks/numerics.lisp

Dependency

functions.lisp (file).

Source

the-cost-of-nothing.asd.

Parent Component

benchmarks (module).

Public Interface

flops (function).

Internals

print-numerics-report (function).

---

4.1.11 the-cost-of-nothing/benchmarks/report.lisp

Dependency

numerics.lisp (file).

Source

the-cost-of-nothing.asd.

Parent Component

benchmarks (module).

Public Interface

print-report (function).

Internals

y-intersection-and-slope (function).

---

6.1.1 Macros

Macro: bench (form &rest args &key max-samples min-sample-time timeout overhead) ¶

Evaluate FORM multiple times and print the averaged execution time to *TRACE-OUTPUT*.

Examples:
(bench nil) => 0.00 nanoseconds
(bench (make-hash-table)) => 247.03 nanoseconds

Package

the-cost-of-nothing.

Source

benchmarking.lisp.

Macro: benchmark (form &rest args &key max-samples min-sample-time timeout overhead) ¶

Execute BODY multiple times to accurately measure its execution time in seconds. The returned values are literally the same as those from an invocation of MEASURE-EXECUTION-TIME with suitable lambdas.

Examples:
(benchmark (cons nil nil)) -> 3.3d-9 1.0 36995264
(benchmark (gc :full t)) -> 0.031 0.9 90

Package

the-cost-of-nothing.

Source

benchmarking.lisp.

Macro: monitor (form &key name) ¶

Monitor VALUE by storing a measurement in *MEASUREMENTS*. If *MEASUREMENTS* is NIL, no measurement is recorded.

The keyword argument NAME can be used to describe the nature of the measurement. The default name of an measurement is the VALUE form that is the first argument of this macro.

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Macro: with-monitoring-region ((name) &body body) ¶

Execute BODY in a region monitoring NAME. This entails the following things:

1. The special variable *MEASUREMENTS* is bound to itself, to ensure that
it has the same value throughout the entire monitoring block.

1. An MONITORING-REGION-START measurement is stored right before executing BODY. Its value is NIL initially, but later set to the corresponding MONITORING-REGION-END measurement.

2. For the dynamic extent of BODY, NAME is prepended to the context of all measurements.

3. A MONITORING-REGION-END measurement is stored once control is transferred outside of BODY. Its value is the corresponding MONITORING-REGION-START measurement.

Package

the-cost-of-nothing.

Source

monitoring.lisp.

---

6.1.2 Ordinary functions

Function: benchmark-thunk (thunk &key timeout min-sample-time max-samples overhead) ¶

Package

the-cost-of-nothing.

Source

benchmarking.lisp.

Function: cons-cost () ¶

Package

the-cost-of-nothing.

Source

memory-management.lisp.

Function: flops (&key element-type) ¶

Package

the-cost-of-nothing.

Source

numerics.lisp.

Function: funcall-cost (&key mandatory-arguments optional-arguments keyword-arguments rest-arguments) ¶

Package

the-cost-of-nothing.

Source

functions.lisp.

Function: gc-cost (&key full) ¶

Package

the-cost-of-nothing.

Source

memory-management.lisp.

Function: make-list-cost (size &key initial-element) ¶

Package

the-cost-of-nothing.

Source

memory-management.lisp.

Function: make-measurement (value name) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: make-sequence-cost (result-type length &key initial-element) ¶

Package

the-cost-of-nothing.

Source

memory-management.lisp.

Reader: measurement-context (instance) ¶

Writer: (setf measurement-context) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Target Slot

context.

Reader: measurement-name (instance) ¶

Writer: (setf measurement-name) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Target Slot

name.

Reader: measurement-timestamp (instance) ¶

Writer: (setf measurement-timestamp) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Target Slot

timestamp.

Reader: measurement-value (instance) ¶

Writer: (setf measurement-value) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Target Slot

value.

Function: measurementp (object) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: print-report (&optional stream) ¶

Package

the-cost-of-nothing.

Source

report.lisp.

Function: print-time (time &optional stream) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Function: touch (object) ¶

Protect OBJECT from compiler optimization.

Package

the-cost-of-nothing.

Source

benchmarking.lisp.

Function: write-si-unit (quantity unit stream) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

---

6.1.3 Standalone methods

Method: print-object ((monitoring-region-start monitoring-region-start) stream) ¶

Source

monitoring.lisp.

Method: print-object ((measurement measurement) stream) ¶

Source

monitoring.lisp.

Method: print-object ((monitoring-region-end monitoring-region-end) stream) ¶

Source

monitoring.lisp.

---

6.1.4 Structures

Structure: measurement ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Direct superclasses

structure-object.

Direct subclasses

• monitoring-region-end.
• monitoring-region-start.

Direct methods

print-object.

Direct slots

Slot: value ¶

Readers

measurement-value.

Writers

(setf measurement-value).

Slot: name ¶

Readers

measurement-name.

Writers

(setf measurement-name).

Slot: context ¶

Initform

the-cost-of-nothing::*context*

Readers

measurement-context.

Writers

(setf measurement-context).

Slot: timestamp ¶

Initform

(the-cost-of-nothing::make-timestamp)

Readers

measurement-timestamp.

Writers

(setf measurement-timestamp).

Structure: monitoring-region-end ¶

A measurement that is only emitted when leaving a monitoring region. Its value is the corresponding monitoring region start.

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Direct superclasses

measurement.

Direct methods

print-object.

Structure: monitoring-region-start ¶

A measurement that is only emitted when entering a monitoring
region. Its value is the corresponding monitoring region end, or NIL, when the region is still active.

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Direct superclasses

measurement.

Direct methods

print-object.

---

6.2.1 Special variables

Special Variable: *context* ¶

A list of the names of all surrounding monitoring regions.

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Special Variable: *default-min-sample-time* ¶

Package

the-cost-of-nothing.

Source

benchmarking.lisp.

Special Variable: *default-overhead* ¶

Package

the-cost-of-nothing.

Source

benchmarking.lisp.

Special Variable: *measurements* ¶

An object suitable as a second argument to STORE-MEASUREMENT.

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Special Variable: *si-prefix-alist* ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Special Variable: *timestamp-function* ¶

Package

the-cost-of-nothing.

Source

timestamps.lisp.

---

6.2.2 Macros

Macro: define-memo-function (name lambda-list &body body) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Macro: with-fuzzy-timestamps ((&key fuzziness) &body body) ¶

Set the timestamp fuzziness for the dynamic extent of BODY. This can be useful for profiling performance critical regions of code, where the cost of measuring the time would otherwise dominate the execution.

A timestamp fuzziness of zero means that each call to MAKE-TIMESTAMP produces a new timestamp. Values bigger than zero mean that MAKE-TIMESTAMP returns the same timestamp for the given number of consecutive calls.

Package

the-cost-of-nothing.

Source

timestamps.lisp.

Macro: with-memoization (key-form &body body) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

---

6.2.3 Ordinary functions

Function: %monitor (value name) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: call-with-fuzzy-timestamps (thunk fuzziness) ¶

Package

the-cost-of-nothing.

Source

timestamps.lisp.

Function: call-with-memoization (key table thunk) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Function: call-with-monitoring-region (name thunk) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: compiled-lambda (lambda-list &rest body) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Function: copy-measurement (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: copy-monitoring-region-end (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: copy-monitoring-region-start (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: execution-time-of-thunk (thunk) ¶

Execute THUNK and return the execution time of THUNK in seconds as a double-float.

Package

the-cost-of-nothing.

Source

benchmarking.lisp.

Function: lambda-list-bindings (lambda-list) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Function: make-argument-list (&key mandatory-arguments optional-arguments keyword-arguments rest-arguments) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Function: make-instance-cost (&key number-of-slots) ¶

Package

the-cost-of-nothing.

Source

memory-management.lisp.

Function: make-lambda-list (&key mandatory-arguments optional-arguments keyword-arguments rest-arguments) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Function: make-monitoring-region-end (name value) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: make-monitoring-region-start (name) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: make-struct-cost (&key number-of-slots) ¶

Package

the-cost-of-nothing.

Source

memory-management.lisp.

Function: make-timestamp () ¶

Package

the-cost-of-nothing.

Source

timestamps.lisp.

Function: monitoring-region-end-context (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: (setf monitoring-region-end-context) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-end-name (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: (setf monitoring-region-end-name) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-end-p (object) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-end-timestamp (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: (setf monitoring-region-end-timestamp) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-end-value (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: (setf monitoring-region-end-value) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-start-context (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: (setf monitoring-region-start-context) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-start-name (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: (setf monitoring-region-start-name) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-start-p (object) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-start-timestamp (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: (setf monitoring-region-start-timestamp) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: monitoring-region-start-value (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: (setf monitoring-region-start-value) (instance) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Function: nth-keyword-name (n) ¶

Package

the-cost-of-nothing.

Source

utilities.lisp.

Function: print-functions-report (&optional stream) ¶

Package

the-cost-of-nothing.

Source

functions.lisp.

Function: print-memory-management-report (&optional stream) ¶

Package

the-cost-of-nothing.

Source

memory-management.lisp.

Function: print-numerics-report (&optional stream) ¶

Package

the-cost-of-nothing.

Source

numerics.lisp.

Function: sample-execution-time-of-thunk (thunk min-sample-time) ¶

Measure the execution time of invoking THUNK more and more often, until the execution time exceeds MIN-SAMPLE-TIME.

Package

the-cost-of-nothing.

Source

benchmarking.lisp.

Function: y-intersection-and-slope (x0 y0 x1 y1) ¶

Package

the-cost-of-nothing.

Source

report.lisp.

---

6.2.4 Generic functions

Generic Reader: measurements (object) ¶

Package

the-cost-of-nothing.

Methods

Reader Method: measurements ((time-series time-series)) ¶

automatically generated reader method

Source

time-series.lisp.

Target Slot

%measurements.

Generic Writer: (setf measurements) (object) ¶

Package

the-cost-of-nothing.

Methods

Writer Method: (setf measurements) ((time-series time-series)) ¶

automatically generated writer method

Source

time-series.lisp.

Target Slot

%measurements.

Generic Function: store-measurement (measurement storage) ¶

Package

the-cost-of-nothing.

Source

monitoring.lisp.

Methods

Method: store-measurement (measurement (null null)) ¶

---

6.2.5 Classes

Class: time-series ¶

Package

the-cost-of-nothing.

Source

time-series.lisp.

Direct methods

• (setf measurements).
• measurements.

Direct slots

Slot: %measurements ¶

Initform

(quote nil)

Readers

measurements.

Writers

(setf measurements).

---