Changes between Version 1 and Version 2 of Trace


Ignore:
Timestamp:
Mar 12, 2008, 10:30:18 PM (11 years ago)
Author:
gz
Comment:

Extensions

Legend:

Unmodified
Added
Removed
Modified
  • Trace

    v1 v2  
    44 
    55 
    6 {{{
    7 TRACE {spec | (spec {option-key value}*)}*    [Macro]
    8 }}}
     6'''`TRACE {keyword global-value}* {spec | (spec {keyword local-value}*)}*        `[Macro]'''
    97
    10 The `trace` macro encapsulates the function named by
    11 ''spec'', causing trace actions to take place on entry and exit from the
    12 function.  The default actions print a message on function entry and exit.
     8The `trace` macro encapsulates the functions named by
     9''spec''s, causing trace actions to take place on entry and exit from each
     10function.  The default actions print a message on function entry and exit,
     11''keyword''/''value'' options can be used to specify changes in the default
     12behavior.
    1313
    1414Invoking `(trace)` without arguments returns a list of functions being traced.
    1515
     16         
     17A ''spec'' is either a symbol that is the name of a function, or an
     18expression of the form `(setf `''symbol''`)`, or a specific method of
     19a generic function in the form
     20`(:method `''gf-name'' `{`''qualifier''`}* ( {`''specializer''`}* ))`, where a
     21''specializer'' can be the name of a class or an `EQL` specializer.
    1622
    17 A ''spec'' is either a symbol that is the name of a function, or an
    18 expression of the form `(setf `''symbol''`)`, or a
    19 specific method of a generic function in the form `(:method `''gf-name''` {`''qualifier''`}* ( {`''specializer''`}* ) )`, where a ''specializer'' can be the name of a class or an `EQL` specializer.
     23A ''spec'' can also be a string naming a package, or equivalently a list `(:package `''package-name''`)`,
     24in order to request that all traceable functions in the package to be traced.
    2025
    2126
    22 By default, whenever a traced function is entered or exited, a short message is printed
    23 on `*trace-output*` showing the arguments on entry and values on exit.
    24 The following ''option-keys'' can be used to modify this behavior:
     27By default, whenever a traced function is entered or exited, a short
     28message is printed on `*trace-output*` showing the arguments on entry
     29and values on exit.  Options specified as key/value pairs can be used
     30to modify this behavior.  Options preceding the function ''spec''s
     31apply to all the functions being traced.  Options specified along with
     32a ''spec'' apply to that spec only. The following ''options'' are
     33supported:
    2534 
    26  `:before` ::
    27  specifies the action to be taken just before the traced function is entered.  The value is one of:
     35 `:before` ''action''::
     36 specifies the action to be taken just before the traced function is entered.  ''action'' is one of:
    2837   * `:print` - The default, prints a short indented message showing the function name and the invocation arguments
    29    * `:break` - Enters the debugger after printing the standard function entry message
     38   * `:break` - Equivalent to `:before :print :break-before t`
     39   * `:backtrace` - Equivalent to `:before :print :backtrace-before t`
    3040   * ''function'' - Any other value is interpreted as a function to call on entry instead of printing the standard entry message.  It is called with its first argument being the name of the function being traced, the remaining arguments being all the arguments to the function being traced, and `ccl:*trace-level*` bound to the current nesting level of trace actions.
    31  `:after` ::
    32  specifies the action to be taken just after the traced function exits.  The value is one of:
     41 `:after` ''action''::
     42 specifies the action to be taken just after the traced function exits.  ''action'' is one of:
    3343   * `:print` - The default, prints a short indented message showing the function name and the returned values
    34    * `:break` - Enters the debugger after printing the standard function exit message
     44   * `:break` - Equivalent to `:after :print :break-after t`
     45   * `:backtrace` - Equivalent to `:after :print :backtrace-after t`
    3546   * ''function'' - Any other value is interpreted as a function to call on exit instead of printing the standard exit message.  It is called with its first argument being the name of the function being traced, the remaining arguments being all the values returned by the function being traced, and `ccl:*trace-level*` bound to the current nesting level of trace actions.
    36  `:backtrace` ::
    37  If true, requests that a stack backtrace (in brief format) be printed whenever the function is invoked. The value can be an integer, in which case it is the maximum number of frames to print. Otherwise, all frames are shown.
     47 `:backtrace {T | nil}`::
     48 If true, requests that a stack backtrace (in brief format) be printed whenever the function is invoked. The value can be an integer, in which case it is the maximum number of frames to print. Otherwise, all frames are shown.
     49 `:methods {T | nil}`::
     50 If true, and if applied to a ''spec'' naming a generic function, arranges to trace all the methods of the generic function in addition to the generic function itself.
     51 `:if `''form''::
     52 `:condition `''form''::
     53 Evaluates ''form'' whenever the function being traced is about to be entered, and inhibits all trace actions if ''form'' returns nil. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. `:condition` is just a synonym for `:if`, though if both are specified, both must return non-nil.
     54 `:before-if `''form''::
     55 Evaluates ''form'' whenever the function being traced is about to be entered, and inhibits the entry trace actions if ''form'' returns nil.  The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. If both `:if` and `:before-if` are specified, both must return non-nil in order for the before entry actions to happen.
     56 `:after-if `''form''::
     57 Evaluates ''form'' whenever the function being traced has just exited, and inhibits the exit trace actions if ''form'' returns nil.  The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. If both `:if` and `:after-if` are specified, both must return non-nil in order for the after exit actions to happen.
     58 `:print-before `''form''::
     59 Evaluates ''form'' whenever the function being traced is about to be entered, and prints the result before printing the standard entry message.  The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.  To see multiple forms, use `values`: `:print-before (values (one-thing) (another-thing))`.
     60 `:print-after `''form''::
     61 Evaluates ''form'' whenever the function being traced has just exited, and prints the result after printing the standard exit message.  The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. To see multiple forms, use `values`: `:print-after (values (one-thing) (another-thing))`.
     62 `:print `''form''::
     63 Equivalent to `:print-before `''form''` :print-after `''form''.
     64 `:eval-before `''form''::
     65 Evaluates ''form'' whenever the function being traced is about to be entered.  The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.
     66 `:eval-after `''form''::
     67 Evaluates ''form'' whenever the function being has just exited.  The form may reference the lexical variable ccl::vals, which is a list of values returned by this call.
     68 `:eval `''form''::
     69 Equivalent to `:eval-before `''form''` :eval-after `''form''.
     70 `:break-before `''form''::
     71 Evaluates ''form'' whenever the function being traced is about to be entered, and if the result is non-nil, enters a debugger break loop.  The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.
     72 `:break-after `''form''::
     73 Evaluates ''form'' whenever the function being traced has just exited, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call.
     74 `:break `''form''::
     75 Equivalent to `:break-before `''form''` :break-after `''form''.
     76 `:backtrace-before `''form''::
     77 `:backtrace `''form''::
     78 Evaluates ''form'' whenever the function being traced is about to be entered.  The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. The value returned by ''form'' is intepreted as follows:
     79  * nil - do nothing.
     80  * `:detailed` - prints a detailed backtrace to `*trace-output*`.
     81  * `(:detailed `''integer''`)` - prints the top ''integer'' frames of detailed backtrace to `*trace-output*`.
     82  * ''integer'' - prints top ''integer'' frames of a terse backtrace to `*trace-output*`.
     83  * anything else - prints a terse backtrace to `*trace-output*`.
     84 Note that unlike with the other options, `:backtrace` is equivalent to `:backtrace-before` only, not both before and after, since it's usually not helpful to print the same backtrace both before and after the function call.
     85 `:backtrace-after `''form'':: 
     86 Evaluates ''form'' whenever the function being traced has just exited.  The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. The value returned by ''form'' is intepreted as follows:
     87  * nil - do nothing.
     88  * `:detailed` - prints a detailed backtrace to `*trace-output*`.
     89  * `(:detailed `''integer''`)` - prints the top ''integer'' frames of detailed backtrace to `*trace-output*`.
     90  * ''integer'' - prints top ''integer'' frames of terse backtrace to `*trace-output*`.
     91  * anything else - prints a terse backtrace to `*trace-output*`.
     92
     93
     94'''`CCL:*TRACE-LEVEL*        `[Variable]'''
     95
     96Variable bound to the current nesting level of tracing while before and after trace actions are executed.
     97
     98'''`TRACE-FUNCTION spec &key {keyword value}*        `[Function]'''
     99
     100This is a functional version of the TRACE macro.  ''spec'' and
     101''keyword''s are as for TRACE, except that all arguments are evaluated.