contrib/sb-sprof/sb-sprof.texinfo

   1 @cindex Profiling, statistical
   2
   3 The @code{sb-sprof} module, loadable by
   4 @lisp
   5 (require :sb-sprof)
   6 @end lisp
   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.
  13
  14 @subsection Example Usage
  15
  16 @lisp
  17 (require :sb-sprof)
  18
  19 (declaim (optimize speed))
  20
  21 (defun cpu-test (n)
  22   (let ((a 0))
  23     (dotimes (i (expt 2 n) a)
  24       (setf a (logxor a
  25                       (* i 5)
  26                       (+ a i))))))
  27
  28 ;;;; CPU profiling
  29
  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
  34                           :report :flat
  35                           :loop nil)
  36   (cpu-test 26))
  37
  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
  43                           :report :flat
  44                           :loop t
  45                           :show-progress t)
  46   (cpu-test 24))
  47
  48 ;;;; Allocation profiling
  49
  50 (defun foo (&rest args)
  51   (mapcar (lambda (x) (float x 1d0)) args))
  52
  53 (defun bar (n)
  54   (declare (fixnum n))
  55   (apply #'foo (loop repeat n collect n)))
  56
  57 (sb-sprof:with-profiling (:max-samples 10000
  58                           :mode :alloc
  59                           :report :flat)
  60   (bar 1000))
  61 @end lisp
  62
  63 @subsection Output
  64
  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.
  68
  69 @lisp
  70            Self        Total        Cumul
  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
  76 @end lisp
  77
  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.
  84
  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
  88 runs.
  89
  90 @lisp
  91 ;      6CF:       702E             JO L4              ; 6/242 samples
  92 ;      6D1:       D1E3             SHL EBX, 1
  93 ;      6D3:       702A             JO L4
  94 ;      6D5: L2:   F6C303           TEST BL, 3         ; 2/242 samples
  95 ;      6D8:       756D             JNE L8
  96 ;      6DA:       8BC3             MOV EAX, EBX       ; 5/242 samples
  97 ;      6DC: L3:   83F900           CMP ECX, 0         ; 4/242 samples
  98 @end lisp
  99
 100 @subsection Platform support
 101
 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.
 107
 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.
 111
 112 @subsection Macros
 113
 114 @include macro-sb-sprof-with-profiling.texinfo
 115 @include macro-sb-sprof-with-sampling.texinfo
 116
 117 @subsection Functions
 118
 119 @include fun-sb-sprof-report.texinfo
 120
 121 @include fun-sb-sprof-reset.texinfo
 122
 123 @include fun-sb-sprof-start-profiling.texinfo
 124
 125 @include fun-sb-sprof-stop-profiling.texinfo
 126
 127 @subsection Variables
 128
 129 @include var-sb-sprof-star-max-samples-star.texinfo
 130
 131 @include var-sb-sprof-star-sample-interval-star.texinfo
 132
 133 @subsection Credits
 134
 135 @code{sb-sprof} is an SBCL port, with enhancements, of Gerd
 136 Moellmann's statistical profiler for CMUCL.