4.4 Advising Procedures

Giving advice to procedures is a powerful debugging technique. trace and break are useful examples of advice-giving procedures. Note that the advice system only works for interpreted procedures.

procedure: trace-entry procedure

Causes an informative message to be printed whenever procedure is entered. The message is of the form

[Entering #[compound-procedure 1 foo]
    Args: val1
          val2
          …]

where val1, val2 etc. are the evaluated arguments supplied to the procedure.

(trace-entry fib)
(fib 3)
-| [Entering #[compound-procedure 19 fib]
-|     Args: 3]
-| [Entering #[compound-procedure 19 fib]
-|     Args: 1]
-| [Entering #[compound-procedure 19 fib]
-|     Args: 2]
⇒ 3

procedure: trace-exit procedure

Causes an informative message to be printed when procedure terminates. The message contains the procedure, its argument values, and the value returned by the procedure.

(trace-exit fib)
(fib 3)
-| [1
-|       <== #[compound-procedure 19 fib]
-|     Args: 1]
-| [2
-|       <== #[compound-procedure 19 fib]
-|     Args: 2]
-| [3
-|       <== #[compound-procedure 19 fib]
-|     Args: 3]
⇒ 3

procedure: trace-both procedure

procedure: trace procedure

Equivalent to calling both trace-entry and trace-exit on procedure. trace is the same as trace-both.

(trace-both fib)
(fib 3)
-| [Entering #[compound-procedure 19 fib]
-|     Args: 3]
-| [Entering #[compound-procedure 19 fib]
-|     Args: 1]
-| [1
-|       <== #[compound-procedure 19 fib]
-|     Args: 1]
-| [Entering #[compound-procedure 19 fib]
-|     Args: 2]
-| [2
-|       <== #[compound-procedure 19 fib]
-|     Args: 2]
-| [3
-|       <== #[compound-procedure 19 fib]
-|     Args: 3]
⇒ 3

procedure: untrace-entry [procedure]

Stops tracing the entry of procedure. If procedure is not given, the default is to stop tracing the entry of all entry-traced procedures.

procedure: untrace-exit [procedure]

Stops tracing the exit of procedure. If procedure is not given, the default is all exit-traced procedures.

procedure: untrace [procedure]

Stops tracing both the entry to and the exit from procedure. If procedure is not given, the default is all traced procedures.

procedure: break-entry procedure

Like trace-entry with the additional effect that a breakpoint is entered when procedure is invoked. Both procedure and its arguments can be accessed by calling the procedures *proc* and *args*, respectively. Use restart or continue to continue from a breakpoint.

procedure: break-exit procedure

Like trace-exit, except that a breakpoint is entered just prior to leaving procedure. Procedure, its arguments, and the result can be accessed by calling the procedures *proc*, *args*, and *result*, respectively. Use restart or continue to continue from a breakpoint.

procedure: break-both procedure

procedure: break procedure

Sets a breakpoint at the beginning and end of procedure. This is break-entry and break-exit combined.

procedure: unbreak [procedure]

Discontinues the entering of a breakpoint on the entry to and exit from procedure. If procedure is not given, the default is all breakpointed procedures.

procedure: unbreak-entry [procedure]

Discontinues the entering of a breakpoint on the entry to procedure. If procedure is not given, the default is all entry-breakpointed procedures.

procedure: unbreak-exit [procedure]

Discontinues the entering of a breakpoint on the exit from procedure. If procedure is not given, the default is all exit-breakpointed procedures.

The following three procedures are valid only within the dynamic extent of a breakpoint. In other words, don’t call them unless you are stopped inside a breakpoint.

procedure: *proc*

Returns the procedure in which the breakpoint has stopped.

procedure: *args*

Returns the arguments to the procedure in which the breakpoint has stopped. The arguments are returned as a newly allocated list.

procedure: *result*

Returns the result yielded by the procedure in which the breakpoint has stopped. This is valid only when in an exit breakpoint.

The following procedures install advice procedures that are called when the advised procedure is entered or exited. An entry-advice procedure must accept three arguments: the advised procedure, a list of the advised procedure’s arguments, and the advised procedure’s application environment (that is, the environment in which the procedure’s formal parameters are bound). An exit-advice procedure must accept four arguments: the advised procedure, a list of the advised procedure’s arguments, the result yielded by the advised procedure, and the advised procedure’s application environment.

Note that the trace and breakpoint procedures described above are all implemented by means of the more general advice procedures, so removing advice from an advised procedure will also remove traces and breakpoints.

procedure: advise-entry procedure advice

Advice must be an entry-advice procedure. Advice is attached to procedure, so that whenever procedure is entered, advice is called.

procedure: advise-exit procedure advice

Advice must be an exit-advice procedure. Advice is attached to procedure, so that whenever procedure returns, advice is called.

procedure: advice procedure

Returns the advice procedures, if any, that are attached to procedure. This is returned as a list of two lists: the first list is all of the entry-advice procedures attached to procedure, and the second is all of the exit-advice procedures.

procedure: unadvise-entry [procedure]

Removes all entry-advice procedures from procedure. If procedure is not given, the default is all entry-advised procedures.

procedure: unadvise-exit [procedure]

Removes exit-advice procedures from procedure. If procedure is not given, the default is all exit-advised procedures.

procedure: unadvise [procedure]

Removes all advice procedures from procedure. This is a combination of unadvise-entry and unadvise-exit. If procedure is not given, the default is all advised procedures.