1 @cindex Profiling, statistical
3 The @code{sb-sprof} module, loadable by
7 provides an alternate profiler which works by taking samples of the
8 program execution at regular intervals, instead of instrumenting
9 functions like @code{sb-profile:profile} does. You might find
10 @code{sb-sprof} more useful than the deterministic profiler when profiling
11 functions in the @code{common-lisp}-package, SBCL internals, or code
12 where the instrumenting overhead is excessive.
14 @subsection Example Usage
19 (declaim (optimize speed))
23 (dotimes (i (expt 2 n) a)
30 ;;; Take up to 1000 samples of running (CPU-TEST 26), and give a flat
31 ;;; table report at the end. Profiling will end one the body has been
32 ;;; evaluated once, whether or not 1000 samples have been taken.
33 (sb-sprof:with-profiling (:max-samples 1000
38 ;;; Take 1000 samples of running (CPU-TEST 24), and give a flat
39 ;;; table report at the end. The body will be re-evaluated in a loop
40 ;;; until 1000 samples have been taken. A sample count will be printed
41 ;;; after each iteration.
42 (sb-sprof:with-profiling (:max-samples 1000
48 ;;;; Allocation profiling
50 (defun foo (&rest args)
51 (mapcar (lambda (x) (float x 1d0)) args))
55 (apply #'foo (loop repeat n collect n)))
57 (sb-sprof:with-profiling (:max-samples 10000
65 The flat report format will show a table of all functions that the
66 profiler encountered on the call stack during sampling, ordered by the
67 number of samples taken while executing that function.
71 Nr Count % Count % Count % Function
72 ------------------------------------------------------------------------
73 1 165 38.3 165 38.3 165 38.3 SB-KERNEL:TWO-ARG-XOR
74 2 141 32.7 141 32.7 306 71.0 SB-VM::GENERIC-+
75 3 67 15.5 145 33.6 373 86.5 CPU-TEST-2
78 For each function, the table will show three absolute and relative
79 sample counts. The Self column shows samples taken while directly
80 executing that function. The Total column shows samples taken while
81 executing that function or functions called from it (sampled to a
82 platform-specific depth). The Cumul column shows the sum of all
83 Self columns up to and including that line in the table.
85 The profiler also hooks into the disassembler such that instructions which
86 have been sampled are annotated with their relative frequency of
87 sampling. This information is not stored across different sampling
91 ; 6CF: 702E JO L4 ; 6/242 samples
92 ; 6D1: D1E3 SHL EBX, 1
94 ; 6D5: L2: F6C303 TEST BL, 3 ; 2/242 samples
96 ; 6DA: 8BC3 MOV EAX, EBX ; 5/242 samples
97 ; 6DC: L3: 83F900 CMP ECX, 0 ; 4/242 samples
100 @subsection Platform support
102 This module is known not to work consistently on the Alpha platform,
103 for technical reasons related to the implementation of a machine
104 language idiom for marking sections of code to be treated as atomic by
105 the garbage collector; However, it should work on other platforms,
106 and the deficiency on the Alpha will eventually be rectified.
108 Allocation profiling is only supported on SBCL builds that use
109 the generational garbage collector. Tracking of call stacks at a
110 depth of more than two levels is only supported on x86 and x86-64.
114 @include macro-sb-sprof-with-profiling.texinfo
115 @include macro-sb-sprof-with-sampling.texinfo
117 @subsection Functions
119 @include fun-sb-sprof-report.texinfo
121 @include fun-sb-sprof-reset.texinfo
123 @include fun-sb-sprof-start-profiling.texinfo
125 @include fun-sb-sprof-stop-profiling.texinfo
127 @subsection Variables
129 @include var-sb-sprof-star-max-samples-star.texinfo
131 @include var-sb-sprof-star-sample-interval-star.texinfo
135 @code{sb-sprof} is an SBCL port, with enhancements, of Gerd
136 Moellmann's statistical profiler for CMUCL.