6.26.4.3 Low-Level Traps

To summarize the last sections, traps are enabled or disabled, and when they are enabled, they add to various VM hooks.

Note, however, that traps do not increase the VM trace level. So if you create a trap, it will be enabled, but unless something else increases the VM’s trace level (see VM Hooks), the trap will not fire. It turns out that getting the VM trace level right is tricky without a global view of what traps are enabled. See Trap States, for Guile’s answer to this problem.

Traps are created by calling procedures. Most of these procedures share a set of common keyword arguments, so rather than document them separately, we discuss them all together here:

#:vm

The VM to instrument. Defaults to the current thread’s VM.

#:current-frame

For traps that enable more hooks depending on their dynamic context, this argument gives the current frame that the trap is running in. Defaults to #f.

To have access to these procedures, you’ll need to have imported the (system vm traps) module:

(use-modules (system vm traps))

Scheme Procedure: trap-at-procedure-call proc handler [#:vm]

A trap that calls handler when proc is applied.

Scheme Procedure: trap-in-procedure proc enter-handler exit-handler [#:current-frame] [#:vm]

A trap that calls enter-handler when control enters proc, and exit-handler when control leaves proc.

Control can enter a procedure via:

• A procedure call.
• A return to a procedure’s frame on the stack.
• A continuation returning directly to an application of this procedure.

Control can leave a procedure via:

• A normal return from the procedure.
• An application of another procedure.
• An invocation of a continuation.
• An abort.

Scheme Procedure: trap-instructions-in-procedure proc next-handler exit-handler [#:current-frame] [#:vm]

A trap that calls next-handler for every instruction executed in proc, and exit-handler when execution leaves proc.

Scheme Procedure: trap-at-procedure-ip-in-range proc range handler [#:current-frame] [#:vm]

A trap that calls handler when execution enters a range of instructions in proc. range is a simple of pairs, ((start . end) ...). The start addresses are inclusive, and end addresses are exclusive.

Scheme Procedure: trap-at-source-location file user-line handler [#:current-frame] [#:vm]

A trap that fires when control reaches a given source location. The user-line parameter is one-indexed, as a user counts lines, instead of zero-indexed, as Guile counts lines.

Scheme Procedure: trap-frame-finish frame return-handler abort-handler [#:vm]

A trap that fires when control leaves the given frame. frame should be a live frame in the current continuation. return-handler will be called on a normal return, and abort-handler on a nonlocal exit.

Scheme Procedure: trap-in-dynamic-extent proc enter-handler return-handler abort-handler [#:vm]

A more traditional dynamic-wind trap, which fires enter-handler when control enters proc, return-handler on a normal return, and abort-handler on a nonlocal exit.

Note that rewinds are not handled, so there is no rewind handler.

Scheme Procedure: trap-calls-in-dynamic-extent proc apply-handler return-handler [#:current-frame] [#:vm]

A trap that calls apply-handler every time a procedure is applied, and return-handler for returns, but only during the dynamic extent of an application of proc.

Scheme Procedure: trap-instructions-in-dynamic-extent proc next-handler [#:current-frame] [#:vm]

A trap that calls next-handler for all retired instructions within the dynamic extent of a call to proc.

Scheme Procedure: trap-calls-to-procedure proc apply-handler return-handler [#:vm]

A trap that calls apply-handler whenever proc is applied, and return-handler when it returns, but with an additional argument, the call depth.

That is to say, the handlers will get two arguments: the frame in question, and the call depth (a non-negative integer).

Scheme Procedure: trap-matching-instructions frame-pred handler [#:vm]

A trap that calls frame-pred at every instruction, and if frame-pred returns a true value, calls handler on the frame.