source: project/wiki/eggref/5/trace @ 37428

[[tags: egg]]
[[toc:]]

== trace

=== Introduction

The extension provides traced execution of procedures and setting breakpoints
on procedure entry.

This replaces the tracing facilities of CHICKEN versions prior to 4.2.12.

=== Requirements

[[/eggref/5/advice|advice]],
[[/eggref/5/miscmacros|miscmacros]]

=== Documentation

==== trace

<procedure>(trace [PROCEDURE ...])</procedure>

Modifies the given procedures by printing some information on entry and exit.
When given no arguments, {{(trace)}} lists all currently traced procedures.

Note that {{PROCEDURE}} may be any procedure and doesn't necessarily
have to be a toplevel definition.

==== untrace

<procedure>(untrace [PROCEDURE ...])</procedure>

Removes tracing from {{PROCEDURE ...}}, which should previously have been
traced with {{trace}}. When given no arguments, {{(untrace)}} removes
untraces all currently traced procedures.

==== trace/untrace

<procedure>(trace/untrace PROCEDURE ...)</procedure>

Toggles tracing on/off for the given procedures.

==== trace-module

<procedure>(trace-module MODULENAME ...)</procedure>

Traces all exported toplevel procedures of the modules with the names given
in {{MODULENAME ...}}.
The module must already be loaded. Note that core-library modules can
not be traced.

==== untrace-module

<procedure>(untrace-module MODULENAME ...)</procedure>

Untraces all currently traced exports of the given modules.

==== break

<procedure>(break [PROCEDURE ...])</procedure>

Modifies the given procedures to signal a condition on entry. The
condition is of the kinds {{exn}} and {{breakpoint}} and will terminate
execution unless caught. In the interpreter, the condition is accessible
on the toplevel using the {{,exn}} command. Use {{(continue)}} to
continue execution. If no arguments are given, {{(break)}} lists all
procedures that currently have breakpoints set.

Note that {{PROCEDURE}} may be any procedure and doesn't necessarily
have to be a toplevel definition.

==== unbreak

<procedure>(unbreak [PROCEDURE ...])</procedure>

Removes breakpoints from the given procedures (or from all, if no arguments
are given).

==== continue

<procedure>(continue [CONDITION])</procedure>
<procedure>(c [CONDITION])</procedure>

Continues execution from the breakpoint that signalled {{CONDITION}}, or
from the last breakpoint if {{CONDITION}} is not given.

==== trace-output-port

<parameter>(trace-output-port [PORT])</parameter>

Specifies the port to which tracing information should be written and
defaults to the value of {{(current-output-port)}}.


=== trace-verbose

<parameter>(trace-verbose [BOOL])</parameter>

If true (the default) show a message when enabling or disabling trace-
or break-points for a procedure.

=== trace-length-limit

<parameter>(trace-length-limit [LIMIT])</parameter>

This allows you to determine the maximum length of the part of the
output that shows the traced procedure plus its arguments.  {{LIMIT}}
is a number of characters, or {{#f}} in case you don't want to limit
it (the default).

=== trace-call-sites

<parameter>(trace-call-sites [BOOL])</parameter>

If true, show call site information in the trace, which makes it
easier to see where the procedure is called from.  This information is
taken from the trace buffer: it shows the most recent entry in that
buffer, so this only works reliably if the call sites aren't optimised
away and are compiled with {{-d2}} or higher (and {{-no-trace}} is
not used).

This option defaults to {{#f}}.

=== trace-call-site-length-limit

<parameter>(trace-call-site-length-limit [LIMIT])</parameter>

When {{trace-call-sites}} is {{#t}}, this allows you to determine the
maximum length of the call site text.  {{LIMIT}} is a number of
characters, or {{#f}} in case you don't want to limit it.

This option defaults to {{100}}

=== License

This code is placed into the public domain.


=== Version history

; 2.0 : Port to CHICKEN 5
; 0.9 : Added {{trace-length-limit}} and added call site tracing (thanks to Matt Welland).
; 0.8 : Changed {{trace-module}} to only trace exported procedures, not other objects.
; 0.7 : Fixed scrutinizer warnings about procedure call with wrong argument count (#842, thanks to Mario Goulart).
; 0.6 : added {{trace-module}} and {{untrace-module}}
; 0.4 : added {{trace/untrace}} and {{trace-verbose}}
; 0.3 : handles non-local exits correctly
; 0.2 : fixed incorrect category
; 0.1 : initial release