1 | [[tags: egg]] |
---|
2 | [[toc:]] |
---|
3 | |
---|
4 | == trace |
---|
5 | |
---|
6 | === Introduction |
---|
7 | |
---|
8 | The extension provides traced execution of procedures and setting breakpoints |
---|
9 | on procedure entry. |
---|
10 | |
---|
11 | This replaces the tracing facilities of CHICKEN versions prior to 4.2.12. |
---|
12 | |
---|
13 | === Requirements |
---|
14 | |
---|
15 | [[/eggref/5/advice|advice]], |
---|
16 | [[/eggref/5/miscmacros|miscmacros]] |
---|
17 | |
---|
18 | === Documentation |
---|
19 | |
---|
20 | ==== trace |
---|
21 | |
---|
22 | <procedure>(trace [PROCEDURE ...])</procedure> |
---|
23 | |
---|
24 | Modifies the given procedures by printing some information on entry and exit. |
---|
25 | When given no arguments, {{(trace)}} lists all currently traced procedures. |
---|
26 | |
---|
27 | Note that {{PROCEDURE}} may be any procedure and doesn't necessarily |
---|
28 | have to be a toplevel definition. |
---|
29 | |
---|
30 | ==== untrace |
---|
31 | |
---|
32 | <procedure>(untrace [PROCEDURE ...])</procedure> |
---|
33 | |
---|
34 | Removes tracing from {{PROCEDURE ...}}, which should previously have been |
---|
35 | traced with {{trace}}. When given no arguments, {{(untrace)}} removes |
---|
36 | untraces all currently traced procedures. |
---|
37 | |
---|
38 | ==== trace/untrace |
---|
39 | |
---|
40 | <procedure>(trace/untrace PROCEDURE ...)</procedure> |
---|
41 | |
---|
42 | Toggles tracing on/off for the given procedures. |
---|
43 | |
---|
44 | ==== trace-module |
---|
45 | |
---|
46 | <procedure>(trace-module MODULENAME ...)</procedure> |
---|
47 | |
---|
48 | Traces all exported toplevel procedures of the modules with the names given |
---|
49 | in {{MODULENAME ...}}. |
---|
50 | The module must already be loaded. Note that core-library modules can |
---|
51 | not be traced. |
---|
52 | |
---|
53 | ==== untrace-module |
---|
54 | |
---|
55 | <procedure>(untrace-module MODULENAME ...)</procedure> |
---|
56 | |
---|
57 | Untraces all currently traced exports of the given modules. |
---|
58 | |
---|
59 | ==== break |
---|
60 | |
---|
61 | <procedure>(break [PROCEDURE ...])</procedure> |
---|
62 | |
---|
63 | Modifies the given procedures to signal a condition on entry. The |
---|
64 | condition is of the kinds {{exn}} and {{breakpoint}} and will terminate |
---|
65 | execution unless caught. In the interpreter, the condition is accessible |
---|
66 | on the toplevel using the {{,exn}} command. Use {{(continue)}} to |
---|
67 | continue execution. If no arguments are given, {{(break)}} lists all |
---|
68 | procedures that currently have breakpoints set. |
---|
69 | |
---|
70 | Note that {{PROCEDURE}} may be any procedure and doesn't necessarily |
---|
71 | have to be a toplevel definition. |
---|
72 | |
---|
73 | ==== unbreak |
---|
74 | |
---|
75 | <procedure>(unbreak [PROCEDURE ...])</procedure> |
---|
76 | |
---|
77 | Removes breakpoints from the given procedures (or from all, if no arguments |
---|
78 | are given). |
---|
79 | |
---|
80 | ==== continue |
---|
81 | |
---|
82 | <procedure>(continue [CONDITION])</procedure> |
---|
83 | <procedure>(c [CONDITION])</procedure> |
---|
84 | |
---|
85 | Continues execution from the breakpoint that signalled {{CONDITION}}, or |
---|
86 | from the last breakpoint if {{CONDITION}} is not given. |
---|
87 | |
---|
88 | ==== trace-output-port |
---|
89 | |
---|
90 | <parameter>(trace-output-port [PORT])</parameter> |
---|
91 | |
---|
92 | Specifies the port to which tracing information should be written and |
---|
93 | defaults to the value of {{(current-output-port)}}. |
---|
94 | |
---|
95 | |
---|
96 | === trace-verbose |
---|
97 | |
---|
98 | <parameter>(trace-verbose [BOOL])</parameter> |
---|
99 | |
---|
100 | If true (the default) show a message when enabling or disabling trace- |
---|
101 | or break-points for a procedure. |
---|
102 | |
---|
103 | === trace-length-limit |
---|
104 | |
---|
105 | <parameter>(trace-length-limit [LIMIT])</parameter> |
---|
106 | |
---|
107 | This allows you to determine the maximum length of the part of the |
---|
108 | output that shows the traced procedure plus its arguments. {{LIMIT}} |
---|
109 | is a number of characters, or {{#f}} in case you don't want to limit |
---|
110 | it (the default). |
---|
111 | |
---|
112 | === trace-call-sites |
---|
113 | |
---|
114 | <parameter>(trace-call-sites [BOOL])</parameter> |
---|
115 | |
---|
116 | If true, show call site information in the trace, which makes it |
---|
117 | easier to see where the procedure is called from. This information is |
---|
118 | taken from the trace buffer: it shows the most recent entry in that |
---|
119 | buffer, so this only works reliably if the call sites aren't optimised |
---|
120 | away and are compiled with {{-d2}} or higher (and {{-no-trace}} is |
---|
121 | not used). |
---|
122 | |
---|
123 | This option defaults to {{#f}}. |
---|
124 | |
---|
125 | === trace-call-site-length-limit |
---|
126 | |
---|
127 | <parameter>(trace-call-site-length-limit [LIMIT])</parameter> |
---|
128 | |
---|
129 | When {{trace-call-sites}} is {{#t}}, this allows you to determine the |
---|
130 | maximum length of the call site text. {{LIMIT}} is a number of |
---|
131 | characters, or {{#f}} in case you don't want to limit it. |
---|
132 | |
---|
133 | This option defaults to {{100}} |
---|
134 | |
---|
135 | === License |
---|
136 | |
---|
137 | This code is placed into the public domain. |
---|
138 | |
---|
139 | |
---|
140 | === Version history |
---|
141 | |
---|
142 | ; 2.0 : Port to CHICKEN 5 |
---|
143 | ; 0.9 : Added {{trace-length-limit}} and added call site tracing (thanks to Matt Welland). |
---|
144 | ; 0.8 : Changed {{trace-module}} to only trace exported procedures, not other objects. |
---|
145 | ; 0.7 : Fixed scrutinizer warnings about procedure call with wrong argument count (#842, thanks to Mario Goulart). |
---|
146 | ; 0.6 : added {{trace-module}} and {{untrace-module}} |
---|
147 | ; 0.4 : added {{trace/untrace}} and {{trace-verbose}} |
---|
148 | ; 0.3 : handles non-local exits correctly |
---|
149 | ; 0.2 : fixed incorrect category |
---|
150 | ; 0.1 : initial release |
---|