3.4.2.7 Breakpoint Behaviours

A breakpoint's behaviour determines what happens when that breakpoint is hit. Several kinds of behaviour are generally useful.

debug-here

Enter the command line debugger. This gives the opportunity to explore the stack, evaluate expressions in any of the pending stack frames, change breakpoint properties or set new breakpoints, and continue program execution when you are done.

trace-here

Trace the current stack frame. For expressions being evaluated, this shows the expression. For procedure applications, it shows the procedure name and its arguments post-evaluation. For both expressions and applications, the indentation of the tracing indicates whether the traced items are mutually tail recursive.

trace-subtree

Trace the current stack frame, and enable tracing for all future evaluations and applications until the current stack frame is exited. trace-subtree is a great preliminary exploration tool when all you know is that there is a bug “somewhere in XXX or in something that XXX calls”.

(at-exit thunk)

Don't do anything now, but arrange for thunk to be executed when the current stack frame is exited. For example, the operation that most debugging tools call “finish” is (at-exit debug-here).

(at-next count thunk)

... arrange for thunk to be executed when beginning the countth next evaluation or application with source location in the current file.

(at-entry count thunk)

... arrange for thunk to be executed when beginning the countth next evaluation (regardless of source location).

(at-apply count thunk)

... arrange for thunk to be executed just before performing the countth next application (regardless of source location).

(at-step count thunk)

Synthesis of at-entry and at-apply; counts both evaluations and applications.

Every breakpoint instance has a slot in which its behaviour is stored. If you have a breakpoint instance in hand, you can change its behaviour using the bp-behaviour accessor.

An accessor supports the setting of a property like this:

     (set! (bp-behaviour breakpoint) new-behaviour)

See the GOOPS manual for further information on accessors.

Alternatively, if you know how to specify the location-args for the breakpoint in question, you can change its behaviour using set-breakpoint!. For example:

     ;; Change behaviour of breakpoint number 2.
     (set-breakpoint! new-behaviour 2)
     
     ;; Change behaviour of procedural breakpoint on [fact1].
     (set-breakpoint! new-behaviour fact1)

In all cases, the behaviour that you specify should be either a single thunk, or a list of thunks, to be called when the breakpoint is hit.

The most common behaviours above are exported as thunks from the (ice-9 debugger behaviour) module. So, if you use this module, you can use those behaviours directly like this:

     (use-modules (ice-9 debugger behaviour))
     (set-breakpoint! trace-subtree 2)
     (set! (bp-behaviour (get-breakpoint 3)) debug-here)

You can also use the list option to combine common behaviours:

     (set-breakpoint! (list trace-here debug-here) 2)

Or, for more customized behaviour, you could build and use your own thunk like this:

     (define (my-behaviour)
       (trace-here)
       (at-exit (lambda ()
                  (display "Exiting frame of my-behaviour bp\n")
                  ... do something unusual ...)))
     
     (set-breakpoint my-behaviour 2)