The metering Reference Manual

This is the metering Reference Manual, version 3.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:19:09 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 metering

Portable Code Profiling Tool

Maintainer

Daniel Kochmański <>

Author

Mark Kantrowitz <>

Home Page

https://gitlab.common-lisp.net/dkochmanski/metering

License

Public Domain

Version

3.2

Source

metering.asd.

Child Component

metering.cl (file).


3 Files

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


3.1 Lisp


3.1.1 metering/metering.asd

Source

metering.asd.

Parent Component

metering (system).

ASDF Systems

metering.


3.1.2 metering/metering.cl

Source

metering.asd.

Parent Component

metering (system).

Packages

monitor.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 monitor

Source

metering.cl.

Nickname

mon

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *monitored-functions*

List of monitored symbols.

Package

monitor.

Source

metering.cl.


5.1.2 Macros

Macro: monitor (&rest names)

Monitor the named functions. As in TRACE, the names are not evaluated. If a function is already monitored, then unmonitor and remonitor (useful to notice function redefinition). If a name is undefined, give a warning and ignore it. See also unmonitor, report-monitoring, display-monitoring-results and reset-time.

Package

monitor.

Source

metering.cl.

Macro: monitor-form (form &optional nested threshold key)

Monitor the execution of all functions in the current package during the execution of FORM. All functions that are executed above THRESHOLD % will be reported.

Package

monitor.

Source

metering.cl.

Macro: unmonitor (&rest names)

Remove the monitoring on the named functions.
Names defaults to the list of all currently monitored functions.

Package

monitor.

Source

metering.cl.

Macro: with-monitoring ((&rest functions) (&optional nested threshold key) &body body)

Monitor the specified functions during the execution of the body.

Package

monitor.

Source

metering.cl.


5.1.3 Ordinary functions

Function: display-monitoring-results (&optional threshold key ignore-no-calls)
Package

monitor.

Source

metering.cl.

Function: monitor-all (&optional package)

Monitor all functions in the specified package.

Package

monitor.

Source

metering.cl.

Function: monitored (function-place)

Test to see if a FUNCTION-PLACE is monitored.

Package

monitor.

Source

metering.cl.

Function: monitoring-encapsulate (name &optional warn)

Monitor the function Name. If already monitored, unmonitor first.

Package

monitor.

Source

metering.cl.

Function: monitoring-unencapsulate (name &optional warn)

Removes monitoring encapsulation code from around Name.

Package

monitor.

Source

metering.cl.

Function: report-monitoring (&optional names nested threshold key ignore-no-calls)

Report the current monitoring state.
The percentage of the total time spent executing unmonitored code in each function (:exclusive mode), or total time (:inclusive mode) will be printed together with the number of calls and
the unmonitored time per call. Functions that have been executed below THRESHOLD % of the time will not be reported.

Package

monitor.

Source

metering.cl.

Function: reset-all-monitoring ()

Reset monitoring info for all functions.

Package

monitor.

Source

metering.cl.

Function: reset-monitoring-info (name)

Reset the monitoring info for the specified function.

Package

monitor.

Source

metering.cl.


5.2 Internals


5.2.1 Constants

Constant: overhead-iterations

Number of iterations over which the timing overhead is averaged.

Package

monitor.

Source

metering.cl.

Constant: precomputed-encapsulations
Package

monitor.

Source

metering.cl.

Constant: time-units-per-second
Package

monitor.

Source

metering.cl.


5.2.2 Special variables

Special Variable: *estimated-total-overhead*
Package

monitor.

Source

metering.cl.

Special Variable: *existing-encapsulations*
Package

monitor.

Source

metering.cl.

Special Variable: *metering-version*

Current version number/date for Metering.

Package

monitor.

Source

metering.cl.

Special Variable: *monitor*

Hash table in which METERING-FUNCTIONS structures are stored.

Package

monitor.

Source

metering.cl.

Special Variable: *monitor-cons-overhead*

The amount of cons an empty monitored function costs.

Package

monitor.

Source

metering.cl.

Special Variable: *monitor-results*

A table of monitoring statistics is stored here.

Package

monitor.

Source

metering.cl.

Special Variable: *monitor-time-overhead*

The amount of time an empty monitored function costs.

Package

monitor.

Source

metering.cl.

Special Variable: *no-calls*

A list of monitored functions which weren’t called.

Package

monitor.

Source

metering.cl.

Special Variable: *total-calls*

Total number of calls monitored so far.

Package

monitor.

Source

metering.cl.

Special Variable: *total-cons*

Total amount of consing monitored so far.

Package

monitor.

Source

metering.cl.

Special Variable: *total-time*

Total amount of time monitored so far.

Package

monitor.

Source

metering.cl.


5.2.3 Macros

Macro: get-cons ()
Package

monitor.

Source

metering.cl.

Macro: get-time ()
Package

monitor.

Source

metering.cl.

Macro: place-function (function-place)

Return the function found at FUNCTION-PLACE. Evals FUNCTION-PLACE if it isn’t a symbol, to allow monitoring of closures located in variables/arrays/structures.

Package

monitor.

Source

metering.cl.

Setf expander for this macro

(setf place-function).


5.2.4 Setf expanders

Setf Expander: (setf place-function) (function-place)

Set the function in FUNCTION-PLACE to FUNCTION.

Package

monitor.

Source

metering.cl.

Reader

place-function (macro).


5.2.5 Ordinary functions

Function: copy-metering-functions (instance)
Package

monitor.

Source

metering.cl.

Function: copy-monitoring-info (instance)
Package

monitor.

Source

metering.cl.

Function: find-encapsulation (min-args optionals-p)
Package

monitor.

Source

metering.cl.

Function: get-monitor-info (name)
Setf Expander: (setf get-monitor-info) (name)
Package

monitor.

Source

metering.cl.

Reader: m-info-calls (instance)
Writer: (setf m-info-calls) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

calls.

Reader: m-info-cons (instance)
Writer: (setf m-info-cons) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

cons.

Reader: m-info-cons-per-call (instance)
Writer: (setf m-info-cons-per-call) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

cons-per-call.

Reader: m-info-name (instance)
Writer: (setf m-info-name) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

name.

Reader: m-info-percent-cons (instance)
Writer: (setf m-info-percent-cons) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

percent-cons.

Reader: m-info-percent-time (instance)
Writer: (setf m-info-percent-time) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

percent-time.

Reader: m-info-time (instance)
Writer: (setf m-info-time) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

time.

Reader: m-info-time-per-call (instance)
Writer: (setf m-info-time-per-call) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

time-per-call.

Function: make-metering-functions (&key name old-definition new-definition read-metering reset-metering)
Package

monitor.

Source

metering.cl.

Function: make-monitoring-encapsulation (min-args optionals-p)
Package

monitor.

Source

metering.cl.

Function: make-monitoring-info (name calls time cons percent-time percent-cons time-per-call cons-per-call)
Package

monitor.

Source

metering.cl.

Reader: metering-functions-name (instance)
Writer: (setf metering-functions-name) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

name.

Reader: metering-functions-new-definition (instance)
Writer: (setf metering-functions-new-definition) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

new-definition.

Reader: metering-functions-old-definition (instance)
Writer: (setf metering-functions-old-definition) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

old-definition.

Function: metering-functions-p (object)
Package

monitor.

Source

metering.cl.

Reader: metering-functions-read-metering (instance)
Writer: (setf metering-functions-read-metering) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

read-metering.

Reader: metering-functions-reset-metering (instance)
Writer: (setf metering-functions-reset-metering) (instance)
Package

monitor.

Source

metering.cl.

Target Slot

reset-metering.

Function: monitor-info-values (name &optional nested warn)

Returns monitoring information values for the named function, adjusted for overhead.

Package

monitor.

Source

metering.cl.

Function: monitoring-info-p (object)
Package

monitor.

Source

metering.cl.

Function: place-fboundp (function-place)

Test to see if FUNCTION-PLACE is a function.

Package

monitor.

Source

metering.cl.

Function: place-macrop (function-place)

Test to see if FUNCTION-PLACE is a macro.

Package

monitor.

Source

metering.cl.

Function: required-arguments (name)
Package

monitor.

Source

metering.cl.

Function: set-monitor-overhead ()

Determines the average overhead of monitoring by monitoring the execution of an empty function many times.

Package

monitor.

Source

metering.cl.

Function: sort-results (&optional key)
Package

monitor.

Source

metering.cl.

Function: stub-function (x)
Package

monitor.

Source

metering.cl.


5.2.6 Structures

Structure: metering-functions
Package

monitor.

Source

metering.cl.

Direct superclasses

structure-object.

Direct slots
Slot: name
Readers

metering-functions-name.

Writers

(setf metering-functions-name).

Slot: old-definition
Type

function

Initform

(error "missing required keyword argument :old-definition")

Readers

metering-functions-old-definition.

Writers

(setf metering-functions-old-definition).

Slot: new-definition
Type

function

Initform

(error "missing required keyword argument :new-definition")

Readers

metering-functions-new-definition.

Writers

(setf metering-functions-new-definition).

Slot: read-metering
Type

function

Initform

(error "missing required keyword argument :read-metering")

Readers

metering-functions-read-metering.

Writers

(setf metering-functions-read-metering).

Slot: reset-metering
Type

function

Initform

(error "missing required keyword argument :reset-metering")

Readers

metering-functions-reset-metering.

Writers

(setf metering-functions-reset-metering).

Structure: monitoring-info
Package

monitor.

Source

metering.cl.

Direct superclasses

structure-object.

Direct slots
Slot: name
Readers

m-info-name.

Writers

(setf m-info-name).

Slot: calls
Readers

m-info-calls.

Writers

(setf m-info-calls).

Slot: time
Package

common-lisp.

Readers

m-info-time.

Writers

(setf m-info-time).

Slot: cons
Package

common-lisp.

Readers

m-info-cons.

Writers

(setf m-info-cons).

Slot: percent-time
Readers

m-info-percent-time.

Writers

(setf m-info-percent-time).

Slot: percent-cons
Readers

m-info-percent-cons.

Writers

(setf m-info-percent-cons).

Slot: time-per-call
Readers

m-info-time-per-call.

Writers

(setf m-info-time-per-call).

Slot: cons-per-call
Readers

m-info-cons-per-call.

Writers

(setf m-info-cons-per-call).


5.2.7 Types

Type: consing-type ()
Package

monitor.

Source

metering.cl.

Type: time-type ()
Package

monitor.

Source

metering.cl.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   F   G   M   P   R   S   U   W  
Index Entry  Section

(
(setf get-monitor-info): Private ordinary functions
(setf m-info-calls): Private ordinary functions
(setf m-info-cons): Private ordinary functions
(setf m-info-cons-per-call): Private ordinary functions
(setf m-info-name): Private ordinary functions
(setf m-info-percent-cons): Private ordinary functions
(setf m-info-percent-time): Private ordinary functions
(setf m-info-time): Private ordinary functions
(setf m-info-time-per-call): Private ordinary functions
(setf metering-functions-name): Private ordinary functions
(setf metering-functions-new-definition): Private ordinary functions
(setf metering-functions-old-definition): Private ordinary functions
(setf metering-functions-read-metering): Private ordinary functions
(setf metering-functions-reset-metering): Private ordinary functions
(setf place-function): Private setf expanders

C
copy-metering-functions: Private ordinary functions
copy-monitoring-info: Private ordinary functions

D
display-monitoring-results: Public ordinary functions

F
find-encapsulation: Private ordinary functions
Function, (setf m-info-calls): Private ordinary functions
Function, (setf m-info-cons): Private ordinary functions
Function, (setf m-info-cons-per-call): Private ordinary functions
Function, (setf m-info-name): Private ordinary functions
Function, (setf m-info-percent-cons): Private ordinary functions
Function, (setf m-info-percent-time): Private ordinary functions
Function, (setf m-info-time): Private ordinary functions
Function, (setf m-info-time-per-call): Private ordinary functions
Function, (setf metering-functions-name): Private ordinary functions
Function, (setf metering-functions-new-definition): Private ordinary functions
Function, (setf metering-functions-old-definition): Private ordinary functions
Function, (setf metering-functions-read-metering): Private ordinary functions
Function, (setf metering-functions-reset-metering): Private ordinary functions
Function, copy-metering-functions: Private ordinary functions
Function, copy-monitoring-info: Private ordinary functions
Function, display-monitoring-results: Public ordinary functions
Function, find-encapsulation: Private ordinary functions
Function, get-monitor-info: Private ordinary functions
Function, m-info-calls: Private ordinary functions
Function, m-info-cons: Private ordinary functions
Function, m-info-cons-per-call: Private ordinary functions
Function, m-info-name: Private ordinary functions
Function, m-info-percent-cons: Private ordinary functions
Function, m-info-percent-time: Private ordinary functions
Function, m-info-time: Private ordinary functions
Function, m-info-time-per-call: Private ordinary functions
Function, make-metering-functions: Private ordinary functions
Function, make-monitoring-encapsulation: Private ordinary functions
Function, make-monitoring-info: Private ordinary functions
Function, metering-functions-name: Private ordinary functions
Function, metering-functions-new-definition: Private ordinary functions
Function, metering-functions-old-definition: Private ordinary functions
Function, metering-functions-p: Private ordinary functions
Function, metering-functions-read-metering: Private ordinary functions
Function, metering-functions-reset-metering: Private ordinary functions
Function, monitor-all: Public ordinary functions
Function, monitor-info-values: Private ordinary functions
Function, monitored: Public ordinary functions
Function, monitoring-encapsulate: Public ordinary functions
Function, monitoring-info-p: Private ordinary functions
Function, monitoring-unencapsulate: Public ordinary functions
Function, place-fboundp: Private ordinary functions
Function, place-macrop: Private ordinary functions
Function, report-monitoring: Public ordinary functions
Function, required-arguments: Private ordinary functions
Function, reset-all-monitoring: Public ordinary functions
Function, reset-monitoring-info: Public ordinary functions
Function, set-monitor-overhead: Private ordinary functions
Function, sort-results: Private ordinary functions
Function, stub-function: Private ordinary functions

G
get-cons: Private macros
get-monitor-info: Private ordinary functions
get-time: Private macros

M
m-info-calls: Private ordinary functions
m-info-cons: Private ordinary functions
m-info-cons-per-call: Private ordinary functions
m-info-name: Private ordinary functions
m-info-percent-cons: Private ordinary functions
m-info-percent-time: Private ordinary functions
m-info-time: Private ordinary functions
m-info-time-per-call: Private ordinary functions
Macro, get-cons: Private macros
Macro, get-time: Private macros
Macro, monitor: Public macros
Macro, monitor-form: Public macros
Macro, place-function: Private macros
Macro, unmonitor: Public macros
Macro, with-monitoring: Public macros
make-metering-functions: Private ordinary functions
make-monitoring-encapsulation: Private ordinary functions
make-monitoring-info: Private ordinary functions
metering-functions-name: Private ordinary functions
metering-functions-new-definition: Private ordinary functions
metering-functions-old-definition: Private ordinary functions
metering-functions-p: Private ordinary functions
metering-functions-read-metering: Private ordinary functions
metering-functions-reset-metering: Private ordinary functions
monitor: Public macros
monitor-all: Public ordinary functions
monitor-form: Public macros
monitor-info-values: Private ordinary functions
monitored: Public ordinary functions
monitoring-encapsulate: Public ordinary functions
monitoring-info-p: Private ordinary functions
monitoring-unencapsulate: Public ordinary functions

P
place-fboundp: Private ordinary functions
place-function: Private macros
place-macrop: Private ordinary functions

R
report-monitoring: Public ordinary functions
required-arguments: Private ordinary functions
reset-all-monitoring: Public ordinary functions
reset-monitoring-info: Public ordinary functions

S
set-monitor-overhead: Private ordinary functions
Setf Expander, (setf get-monitor-info): Private ordinary functions
Setf Expander, (setf place-function): Private setf expanders
sort-results: Private ordinary functions
stub-function: Private ordinary functions

U
unmonitor: Public macros

W
with-monitoring: Public macros


A.3 Variables

Jump to:   *  
C   N   O   P   R   S   T  
Index Entry  Section

*
*estimated-total-overhead*: Private special variables
*existing-encapsulations*: Private special variables
*metering-version*: Private special variables
*monitor*: Private special variables
*monitor-cons-overhead*: Private special variables
*monitor-results*: Private special variables
*monitor-time-overhead*: Private special variables
*monitored-functions*: Public special variables
*no-calls*: Private special variables
*total-calls*: Private special variables
*total-cons*: Private special variables
*total-time*: Private special variables

C
calls: Private structures
cons: Private structures
cons-per-call: Private structures
Constant, overhead-iterations: Private constants
Constant, precomputed-encapsulations: Private constants
Constant, time-units-per-second: Private constants

N
name: Private structures
name: Private structures
new-definition: Private structures

O
old-definition: Private structures
overhead-iterations: Private constants

P
percent-cons: Private structures
percent-time: Private structures
precomputed-encapsulations: Private constants

R
read-metering: Private structures
reset-metering: Private structures

S
Slot, calls: Private structures
Slot, cons: Private structures
Slot, cons-per-call: Private structures
Slot, name: Private structures
Slot, name: Private structures
Slot, new-definition: Private structures
Slot, old-definition: Private structures
Slot, percent-cons: Private structures
Slot, percent-time: Private structures
Slot, read-metering: Private structures
Slot, reset-metering: Private structures
Slot, time: Private structures
Slot, time-per-call: Private structures
Special Variable, *estimated-total-overhead*: Private special variables
Special Variable, *existing-encapsulations*: Private special variables
Special Variable, *metering-version*: Private special variables
Special Variable, *monitor*: Private special variables
Special Variable, *monitor-cons-overhead*: Private special variables
Special Variable, *monitor-results*: Private special variables
Special Variable, *monitor-time-overhead*: Private special variables
Special Variable, *monitored-functions*: Public special variables
Special Variable, *no-calls*: Private special variables
Special Variable, *total-calls*: Private special variables
Special Variable, *total-cons*: Private special variables
Special Variable, *total-time*: Private special variables

T
time: Private structures
time-per-call: Private structures
time-units-per-second: Private constants