doc/ref/scheme-debugging.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @node Tracing
   8 @section Tracing
   9
  10 The @code{(ice-9 debug)} module implements tracing of procedure
  11 applications.  When a procedure is @dfn{traced}, it means that every
  12 call to that procedure is reported to the user during a program run.
  13 The idea is that you can mark a collection of procedures for tracing,
  14 and Guile will subsequently print out a line of the form
  15
  16 @lisp
  17 |  |  [@var{procedure} @var{args} @dots{}]
  18 @end lisp
  19
  20 whenever a marked procedure is about to be applied to its arguments.
  21 This can help a programmer determine whether a function is being called
  22 at the wrong time or with the wrong set of arguments.
  23
  24 In addition, the indentation of the output is useful for demonstrating
  25 how the traced applications are or are not tail recursive with respect
  26 to each other.  Thus, a trace of a non-tail recursive factorial
  27 implementation looks like this:
  28
  29 @lisp
  30 [fact1 4]
  31 |  [fact1 3]
  32 |  |  [fact1 2]
  33 |  |  |  [fact1 1]
  34 |  |  |  |  [fact1 0]
  35 |  |  |  |  1
  36 |  |  |  1
  37 |  |  2
  38 |  6
  39 24
  40 @end lisp
  41
  42 While a typical tail recursive implementation would look more like this:
  43
  44 @lisp
  45 [fact2 4]
  46 [facti 1 4]
  47 [facti 4 3]
  48 [facti 12 2]
  49 [facti 24 1]
  50 [facti 24 0]
  51 24
  52 @end lisp
  53
  54 @deffn {Scheme Procedure} trace procedure
  55 Enable tracing for @code{procedure}.  While a program is being run,
  56 Guile will print a brief report at each call to a traced procedure,
  57 advising the user which procedure was called and the arguments that were
  58 passed to it.
  59 @end deffn
  60
  61 @deffn {Scheme Procedure} untrace procedure
  62 Disable tracing for @code{procedure}.
  63 @end deffn
  64
  65 Here is another example:
  66
  67 @lisp
  68 (define (rev ls)
  69   (if (null? ls)
  70       '()
  71       (append (rev (cdr ls))
  72               (cons (car ls) '())))) @result{} rev
  73
  74 (trace rev) @result{} (rev)
  75
  76 (rev '(a b c d e))
  77 @result{} [rev (a b c d e)]
  78    |  [rev (b c d e)]
  79    |  |  [rev (c d e)]
  80    |  |  |  [rev (d e)]
  81    |  |  |  |  [rev (e)]
  82    |  |  |  |  |  [rev ()]
  83    |  |  |  |  |  ()
  84    |  |  |  |  (e)
  85    |  |  |  (e d)
  86    |  |  (e d c)
  87    |  (e d c b)
  88    (e d c b a)
  89    (e d c b a)
  90 @end lisp
  91
  92 Note the way Guile indents the output, illustrating the depth of
  93 execution at each procedure call.  This can be used to demonstrate, for
  94 example, that Guile implements self-tail-recursion properly:
  95
  96 @lisp
  97 (define (rev ls sl)
  98   (if (null? ls)
  99       sl
 100       (rev (cdr ls)
 101            (cons (car ls) sl)))) @result{} rev
 102
 103 (trace rev) @result{} (rev)
 104
 105 (rev '(a b c d e) '())
 106 @result{} [rev (a b c d e) ()]
 107    [rev (b c d e) (a)]
 108    [rev (c d e) (b a)]
 109    [rev (d e) (c b a)]
 110    [rev (e) (d c b a)]
 111    [rev () (e d c b a)]
 112    (e d c b a)
 113    (e d c b a)
 114 @end lisp
 115
 116 Since the tail call is effectively optimized to a @code{goto} statement,
 117 there is no need for Guile to create a new stack frame for each
 118 iteration.  Tracing reveals this optimization in operation.
 119
 120
 121 @c Local Variables:
 122 @c TeX-master: "guile.texi"
 123 @c End: