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 kw-contexts subfunctions

Arguments

symbols

A symbol or a list of symbols.

packages

A valid package name, or a list of package names, :none 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.

kw-contexts

t or a list of KnowledgeWorks context names.

subfunctions

A boolean.

Values

The time interval is returned.

Description

set-up-profiler is used to declare the values of the parameters of the profiling function.

packages specifies that the symbols in these packages should be monitored, that is added to *profile-symbol-list*. If packages is :all, then symbols in all packages are monitored. If packages is :none , then no package is used to find symbols to monitor. Otherwise, packages should be a list of package specifiers, and the symbols in these packages are monitored.

If symbols is non-nil, it should be a list of function-dspecs to monitor in addition to the symbols that were specified by packages. These are typically symbols, but can be other functions as specified in Function dspecs.

Note: When a symbol that names a generic function should be monitored, LispWorks adds all the methods of the generic function to the profile list.

If both packages and symbols are nil, then set-up-profiler behaves as if packages is :all. Thus if you actually want to monitor no symbols, you need to pass :packages :none. That is useful if you want to monitor only KnowledgeWorks rules (see kw-contexts below).

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.

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 in SMP LispWorks and t in non-SMP LispWorks. This is because the counting significantly affects the performance of applications using Symmetric Multiprocessing (SMP).

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.

kw-contexts allows you to profile forward chaining rules in KnowledgeWorks (see the KnowledgeWorks and Prolog User Guide ). When kw-contexts is t (the default), all context are profiled. Otherwise it should be a list of context names. The profiler profiles all the forward rules in each context.

subfunctions controls whether to profile subfunctions of the functions that are profiled. When it is non-nil, for each function that the profiler is profiling, the profiler checks if it has subfunctions, and if it has then it profiles them too. The default value of subfunctions is nil.

If subfunctions is non-nil then initializing the profiler is somewhat slower, and also, because the names of subfunctions are long, the output is more messy. It is sometimes useful though.

Notes

1. If the profiler is invoked before any call to set-up-profiler, it calls set-up-profiler implicitly without any arguments. That means it will monitor all symbols in the image, and if KnowledgeWorks is loaded also all forward chaining rules. In most cases this is a useful behavior, so it is not necessary to use set-up-profiler.
2. set-up-profiler finds all the symbols in the specified packages at the time it is called. Thus symbols that are give function definitions after the call to set-up-profiler are not profiled, whether or not they are in packages that were passed to set-up-profiler. If you want to ensure that all symbols are profiled, you need to call set-up-profiler just before invoking the profiler.
3. 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.
4. 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.
5. limit, cutoff and collapse affect only the display of the results, not the collection of profiler data.

Examples

(set-up-profiler :packages '(my-package common-lisp))

(set-up-profiler :symbols 

                 (my-list-all-interesting-functions))

See also

*default-profiler-collapse*
*default-profiler-cutoff*
*default-profiler-limit*
profile
start-profiling
stop-profiling
The Profiler