Previous: Accurate Profiler, Up: Profiling


14.2 Statistical Profiler

The sb-sprof module, loadable by

     (require :sb-sprof)

provides an alternate profiler which works by taking samples of the program execution at regular intervals, instead of instrumenting functions like sb-profile:profile does. You might find sb-sprof more useful than accurate profiler when profiling functions in the common-lisp-package, SBCL internals, or code where the instrumenting overhead is excessive.

This module is known not to work consistently on the Alpha platform, for technical reasons related to the implementation of a machine language idiom for marking sections of code to be treated as atomic by the garbage collector; However, it should work on other platforms, and the deficiency on the Alpha will eventually be rectified.

14.2.1 Example Usage

     (require :sb-sprof)
     (sb-sprof:start-profiling)
     
     (defvar *a* 0)
     (dotimes (i (expt 2 26))
       (setf *a* (logxor *a* (* i 5)
                         (+ *a* i))))
     
     (sb-sprof:stop-profiling)
     (sb-sprof:report)

The profiler hooks into the disassembler such that instructions which have been sampled are annotated with their relative frequency of sampling. This information is not stored across different sampling runs.

14.2.2 Functions

— Function: sb-sprof:report &key type max min-percent call-graph stream show-progress

Report statistical profiling results. The following keyword args are recognized:

:Type <type>
Specifies the type of report to generate. If :flat, show flat report, if :graph show a call graph and a flat report. If nil, don't print out a report.
:Stream <stream>
Specify a stream to print the report on. Default is *Standard-Output*.
:Max <max>
Don't show more than <max> entries in the flat report.
:Min-Percent <min-percent>
Don't show functions taking less than <min-percent> of the total time in the flat report.
:Show-Progress <bool>
If true, print progress messages while generating the call graph.
:Call-Graph <graph>
Print a report from <graph> instead of the latest profiling results.

Value of this function is a Call-Graph object representing the resulting call-graph.

— Function: sb-sprof:reset

Reset the profiler.

— Function: sb-sprof:start-profiling &key max-samples sample-interval sampling

Start profiling statistically if not already profiling. The following keyword args are recognized:

:Sample-Interval <seconds>
Take a sample every <seconds> seconds. Default is *Sample-Interval*.
:Max-Samples <max>
Maximum number of samples. Default is *Max-Samples*.
:Sampling <bool>
If true, the default, start sampling right away. If false, Start-Sampling can be used to turn sampling on.

— Function: sb-sprof:stop-profiling

Stop profiling if profiling.

14.2.3 Macros

— Macro: sb-sprof:with-profiling (&key sample-interval max-samples reset show-progress report) &body body

Repeatedly evaluate Body with statistical profiling turned on. The following keyword args are recognized:

:Sample-Interval <seconds>
Take a sample every <seconds> seconds. Default is *Sample-Interval*.
:Max-Samples <max>
Repeat evaluating body until <max> samples are taken. Default is *Max-Samples*.
:Report <type>
If specified, call Report with :Type <type> at the end.
:Reset <bool>
It true, call Reset at the beginning.

14.2.4 Variables

— Variable: sb-sprof:*max-samples*

Default number of samples taken.

— Variable: sb-sprof:*sample-interval*

Default number of seconds between samples.

14.2.5 Credits

sb-sprof is an SBCL port, with enhancements, of Gerd Moellmann's statistical profiler for CMUCL.