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:
The VM to instrument. Defaults to the current thread’s VM.
For traps that enable more hooks depending on their dynamic context,
this argument gives the current frame that the trap is running in.
To have access to these procedures, you’ll need to have imported the
(system vm traps) module:
(use-modules (system vm traps))
A trap that calls handler when proc is applied.
A trap that calls enter-handler when control enters proc, and exit-handler when control leaves proc.
Control can enter a procedure via:
Control can leave a procedure via:
A trap that calls next-handler for every instruction executed in proc, and exit-handler when execution leaves proc.
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.
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.
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.
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.
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.
A trap that calls next-handler for all retired instructions within the dynamic extent of a call to proc.
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).
A trap that calls frame-pred at every instruction, and if frame-pred returns a true value, calls handler on the frame.