Changeset 8669


Ignore:
Timestamp:
Mar 6, 2008, 4:05:09 PM (12 years ago)
Author:
gz
Message:

document TRACE

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/using.xml

    r8664 r8669  
    2424  </sect1>
    2525
     26  <sect1 id="Trace"><title>Trace</title>
     27
     28  <para>
     29    &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
     30    <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
     31    over tracing actions.
     32  </para>
     33
     34
     35  <para>
     36  <command><varname>TRACE</varname> {<replaceable>spec</replaceable> |
     37  (<replaceable>spec</replaceable> {<replaceable>option-key</replaceable>
     38  <replaceable>value</replaceable>}*)}* [Macro]</command>
     39  </para>
     40
     41  <para>
     42    The <varname>trace</varname> macro encapsulates the function named by
     43    <replaceable>spec</replaceable>, causing trace actions to take place on entry and exit from the
     44    function.  The default actions print a message on function entry and exit.
     45  </para>
     46
     47  <para>
     48    Invoking <varname>(trace)</varname> without arguments returns a list of functions being traced.
     49  </para>
     50     
     51  <para>
     52    A <replaceable>spec</replaceable> is either a symbol that is the name of a function, or an
     53    expression of the form <varname>(setf <replaceable>symbol</replaceable>)</varname>, or a
     54    specific method of a generic function in the form <varname>(:method
     55    <replaceable>gf-name</replaceable> {<replaceable>qualifier</replaceable>}* (
     56    {<replaceable>specializer</replaceable>}* ) )</varname>, where a
     57    <replaceable>specializer</replaceable> can be the name of a class or an <varname>EQL</varname>
     58    specializer.
     59  </para>
     60
     61   <para>By default, whenever a traced function is entered or exited, a short message is printed
     62   on <varname>*trace-output*</varname> showing the arguments on entry and values on exit.
     63   The following <replaceable>option-keys</replaceable> can be used to modify this behavior:</para>
     64
     65   <variablelist>
     66     <varlistentry>
     67       <term><varname>:before</varname></term>
     68       <listitem>
     69         <para>specifies the action to be taken just before the traced function is entered.  The
     70         value is one of:</para>
     71         <variablelist>
     72           <varlistentry>
     73             <term><varname>:print</varname></term>
     74             <listitem>
     75               <para>The default, prints a short indented message showing the function name and the invocation arguments </para>
     76             </listitem>
     77           </varlistentry>
     78           <varlistentry>
     79             <term><varname>:break</varname></term>
     80             <listitem>
     81             <para>Enters the debugger after printing the standard function entry message</para>
     82             </listitem>
     83           </varlistentry>
     84           <varlistentry>
     85             <term><replaceable>function</replaceable></term>
     86             <listitem>
     87               <para>Any other value is interpreted as a function to
     88               call on entry instead of printing the standard entry
     89               message.  It is called with its first argument being
     90               the name of the function being traced, the
     91               remaining arguments being all the arguments to the function
     92               being traced, and ccl:*trace-level* bound to the current
     93               nesting level of trace actions.
     94               </para>
     95             </listitem>
     96           </varlistentry>
     97         </variablelist>
     98       </listitem>
     99     </varlistentry>
     100
     101     <varlistentry>
     102       <term><varname>:after</varname></term>
     103       <listitem>
     104         <para>specifies the action to be taken just after the traced function exits.  The
     105         value is one of:</para>
     106         <variablelist>
     107           <varlistentry>
     108             <term><varname>:print</varname></term>
     109             <listitem>
     110               <para>The default, prints a short indented message showing the function name and the
     111               returned values </para>
     112             </listitem>
     113           </varlistentry>
     114           <varlistentry>
     115             <term><varname>:break</varname></term>
     116             <listitem>
     117             <para>Enters the debugger after printing the standard function exit message</para>
     118             </listitem>
     119           </varlistentry>
     120           <varlistentry>
     121             <term><replaceable>function</replaceable></term>
     122             <listitem>
     123               <para>Any other value is interpreted as a function to
     124               call on exit instead of printing the standard exit
     125               message.  It is called with its first argument being
     126               the name of the function being traced, the
     127               remaining arguments being all the values returned by the function
     128               being traced, and ccl:*trace-level* bound to the current
     129               nesting level of trace actions.
     130               </para>
     131             </listitem>
     132           </varlistentry>
     133         </variablelist>
     134       </listitem>
     135     </varlistentry>
     136
     137
     138     <varlistentry>
     139       <term><varname>:backtrace</varname></term>
     140       <listitem>
     141         <para>If true, requests that a stack backtrace (in brief format) be printed whenever the function is
     142         invoked. The value can be an integer, in which case it is the maximum number of frames to
     143         print. Otherwise, all frames are shown.
     144         </para>
     145       </listitem>
     146     </varlistentry>
     147
     148
     149
     150   </variablelist>
     151  </sect1>
     152
    26153</chapter>
Note: See TracChangeset for help on using the changeset viewer.