source: project/wiki/eggref/4/trace @ 33688

Last change on this file since 33688 was 33688, checked in by sjamaan, 4 years ago

Update trace docs with new call-site and length limitations.

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