Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
afc4ccd4 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
07d83abe | 7 | @node Tracing |
24dbb5ed | 8 | @section Tracing |
07d83abe MV |
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 | ||
aba0dff5 | 16 | @lisp |
07d83abe | 17 | | | [@var{procedure} @var{args} @dots{}] |
aba0dff5 | 18 | @end lisp |
07d83abe MV |
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 | ||
aba0dff5 | 29 | @lisp |
07d83abe MV |
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 | |
aba0dff5 | 40 | @end lisp |
07d83abe MV |
41 | |
42 | While a typical tail recursive implementation would look more like this: | |
43 | ||
aba0dff5 | 44 | @lisp |
07d83abe MV |
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 | |
aba0dff5 | 52 | @end lisp |
07d83abe MV |
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 | ||
afc4ccd4 KR |
121 | @c Local Variables: |
122 | @c TeX-master: "guile.texi" | |
123 | @c End: |