Function

Summary

Declares the parameter values of the profiling function.

Package

hcl

Signature

set-up-profiler &key symbols packages kind interval limit cutoff collapse style gc call-counter show-unknown-frames

Arguments

symbols

A symbol or a list of symbols.

packages

A valid package name, or a list of package names, or :all.

kind

:profile, :virtual or :real.

interval

An integer greater than or equal to 10000.

limit

An integer or nil.

cutoff

An integer or nil.

collapse

A generalized boolean.

style

:tree, :list or nil.

gc

A generalized boolean.

call-counter

A generalized boolean.

show-unknown-frames

A generalized boolean.

Values

The time interval is returned.

Description

set-up-profiler is used to declare the values of the parameters of the profiling function. Three values are required, as follows.

symbols, if non-nil, specifies which symbols are to be monitored by the profiler. Each symbol in symbols is checked to see if it is suitable for profiling and if so it is added to the list *profile-symbol-list*.

If symbols is not passed then packages specifies which symbols are to be monitored. If packages is :all, then all packages are monitored. All the symbols in the packages are checked as above. If a symbols argument is present then packages is ignored.

kind specifies the way that the time between samples is measured on Unix-like platforms:

:profile

Process time only.

:virtual

Process time and system time for the process.

:real

Real time.

The default value of kind is :profile.

Note: kind is ignored on Microsoft Windows platforms.

interval specifies the interval in microseconds between profile samples. The minimum value of interval is 10000, that is 10 ms. The default value of interval is 10000.

limit, when non-nil, sets *default-profiler-limit*. This limits the maximum number of lines printed in the profile output (not including the tree). The default value is 100.

cutoff, when non-nil, sets *default-profiler-cutoff*. This is the default minimum percentage that the profiler will display in the output tree. Functions below this percentage will not be displayed. The default is nil, that is there is no cutoff.

collapse specifies whether functions with only one callee in the profile tree should be collapsed, that is, only the child is printed. When passed, sets *default-profiler-collapse*. The default value of collapse is nil.

style controls the format of output. If style is not passed or passed as nil, the format does not change. If style is passed, it can take these values:

:list

The profiler will show the functions seen on the stack.

:tree

The profiler will generate a tree of calls seen in the profiler, as well as the output shown by :list.

The default value of style is :tree.

gc specifies whether to profile functions inside the memory management code (more accurately, functions that are called on the GC stack) in addition to any other profiling. The default value of gc is nil.

show-unknown-frames controls whether the profile tree shows nodes where the name of the function is unknown. The default value of show-unknown-frames is nil.

call-counter specifies whether to add extra code to count calls. The counting is done dynamically. If call-counter is nil, call counters are not added, and the call counter of all functions is displayed as 0. The default value of call-counter is nil on Intel-based platforms and t on other platforms. This is because the counting significantly affects the performance of applications using Symmetric Multiprocessing (SMP).

Notes

1. Call counting can affect performance significantly on some platforms. To get accurate timing (in scales of a few percentage points), pass call-counter nil. However, in most cases the profiler is used to find bottlenecks where the slowdown is hundreds of percentage points and so the effect of call counting is less significant.
2. call-counter is effective only on x86 platforms or in 64-bit LispWorks. On non-x86 platforms 32-bit LispWorks does call counting for a given function if the compiler optimize quality debug is greater than 0 at compile-time, and call-counter has no effect.

Example

(set-up-profiler :symbols '(car cdr)

                 :interval 50000)

On Unix/Linux/Mac OS X:

(set-up-profiler :symbols '(car cdr)

                 :kind :profile :interval 50000)

See also

add-symbol-profiler
*default-profiler-collapse*
*default-profiler-cutoff*
*default-profiler-limit*
profile
*profile-symbol-list*
remove-symbol-profiler