@menu
* Capturing the Stack or Innermost Stack Frame::
-* Examining the Stack::
-* Examining Stack Frames::
+* Stacks::
+* Frames::
* Source Properties:: Remembering the source of an expression.
* Starting a New Stack::
@end menu
@end deffn
-@node Examining the Stack
-@subsubsection Examining the Stack
+@node Stacks
+@subsubsection Stacks
@deffn {Scheme Procedure} stack? obj
@deffnx {C Function} scm_stack_p (obj)
@end deffn
-@node Examining Stack Frames
-@subsubsection Examining Stack Frames
+@node Frames
+@subsubsection Frames
@deffn {Scheme Procedure} frame? obj
@deffnx {C Function} scm_frame_p (obj)
Once you have a captured stack, you can interrogate and display its
details in any way that you want, using the @code{stack-@dots{}} and
-@code{frame-@dots{}} API described in @ref{Examining the Stack} and
-@ref{Examining Stack Frames}.
+@code{frame-@dots{}} API described in @ref{Stacks} and
+@ref{Frames}.
If you want to print out a backtrace in the same format that the Guile
REPL does, you can use the @code{display-backtrace} procedure to do so.
@subsection Traps
@cindex Traps
-@cindex Evaluator trap calls
+@cindex VM hooks
@cindex Breakpoints
@cindex Trace
@cindex Tracing
@cindex Code coverage
@cindex Profiling
Guile's virtual machine can be configured to call out at key points to
-arbitrary user-specified procedures. For more information on these
-hooks, and the circumstances under which the VM calls them, see @ref{VM
-Behaviour}.
-
-In principle, these hooks allow Scheme code to implement any model it
-chooses for examining the evaluation stack as program execution
-proceeds, and for suspending execution to be resumed later. Possible
-applications of this feature include breakpoints, runtime tracing, code
-coverage, and profiling.
-
-@cindex Trap classes
-@cindex Trap objects
-Based on these low level trap calls, Guile provides a higher level,
-object-oriented interface for the manipulation of traps. Different
-kinds of trap are represented as GOOPS classes; for example, the
-@code{<procedure-trap>} class describes traps that are triggered by
-invocation of a specified procedure. A particular instance of a trap
-class --- or @dfn{trap object} --- describes the condition under which
-a single trap will be triggered, and what will happen then; for
-example, an instance of @code{<procedure-trap>} whose @code{procedure}
-and @code{behaviour} slots contain @code{my-factorial} and
-@code{debug-trap} would be a trap that enters the command line
-debugger when the @code{my-factorial} procedure is invoked.
+arbitrary user-specified procedures.
+
+In principle, these @dfn{hooks} allow Scheme code to implement any model
+it chooses for examining the evaluation stack as program execution
+proceeds, and for suspending execution to be resumed later.
+
+VM hooks are very low-level, though, and so Guile also has a library of
+higher-level @dfn{traps} on top of the VM hooks. A trap is an execution
+condition that, when fulfilled, will fire a handler. For example, Guile
+defines a trap that fires when control reaches a certain source
+location.
+
+Finally, Guile also defines a third level of abstractions: per-thread
+@dfn{trap states}. A trap state exists to give names to traps, and to
+hold on to the set of traps so that they can be enabled, disabled, or
+removed. The trap state infrastructure defines the most useful
+abstractions for most cases. For example, Guile's REPL uses trap state
+functions to set breakpoints and tracepoints.
The following subsections describe all this in detail, for both the
user wanting to use traps, and the developer interested in
understanding how the interface hangs together.
-@subsubsection Actually, this section is bitrotten
+@menu
+* VM Hooks:: Modifying Guile's virtual machine.
+* Trap Interface:: Traps are on or off.
+* Low-Level Traps:: The various kinds of low-level traps.
+* Tracing Traps:: Traps to trace procedure calls and returns.
+* Trap States:: One state (per thread) to bind them.
+* Trap Handlers:: What to do when a trap in a trap state fires.
+* Setting Traps:: The highest-level trap interface. Use this.
+@end menu
-Dear reader: the following sections have some great ideas, and some code
-that just needs a few days of massaging to get it to work with the VM
-(as opposed to the old interpreter). Want to help? Yes? Yes!
-@code{guile-devel@@gnu.org}, that's where.
+@node VM Hooks
+@subsubsection VM Hooks
-@subsubsection A Quick Note on Terminology
+Everything that runs in Guile runs on its virtual machine, a C program
+that defines a number of operations that Scheme programs can
+perform.
-@cindex Trap terminology
-It feels natural to use the word ``trap'' in some form for all levels
-of the structure just described, so we need to be clear on the
-terminology we use to describe each particular level. The terminology
-used in this subsection is as follows.
+Note that there are multiple VM ``engines'' for Guile. Only some of them
+have support for hooks compiled in. Normally the deal is that you get
+hooks if you are running interactively, and otherwise they are disabled,
+as they do have some overhead (about 10 or 20 percent).
-@itemize @bullet
-@item
-@cindex Evaluator trap calls
-@cindex Low level trap calls
-``Low level trap calls'', or ``low level traps'', are the calls made
-directly from the C code of the Guile evaluator.
+To ensure that you are running with hooks, pass @code{--debug} to Guile
+when running your program, or otherwise use the @code{call-with-vm} and
+@code{set-vm-engine!} procedures to ensure that you are running in a VM
+with the @code{debug} engine.
-@item
-@cindex Trap classes
-``Trap classes'' are self-explanatory.
+To digress, Guile's VM has 6 different hooks (@pxref{Hooks}) that can be
+fired at different times, which may be accessed with the following
+procedures.
-@item
-@cindex Trap objects
-``Trap objects'', ``trap instances'', or just ``traps'', are instances
-of a trap class, and each describe a single logical trap condition
-plus behaviour as specified by the user of this interface.
-@end itemize
+All hooks are called with one argument, the frame in
+question. @xref{Frames}. Since these hooks may be fired very frequently,
+Guile does a terrible thing: it allocates the frames on the C stack
+instead of the garbage-collected heap.
-A good example of when it is important to be clear, is when we talk
-below of behaviours that should only happen once per low level trap.
-A single low level trap call will typically map onto the processing of
-several trap objects, so ``once per low level trap'' is significantly
-different from ``once per trap''.
+The upshot here is that the frames are only valid within the dynamic
+extent of the call to the hook. If a hook procedure keeps a reference to
+the frame outside the extent of the hook, bad things will happen.
+The interface to hooks is provided by the @code{(system vm vm)} module:
-@menu
-* How to Set a Trap::
-* Specifying Trap Behaviour::
-* Trap Context::
-* Tracing Examples::
-* Tracing Configuration::
-* Tracing and (ice-9 debug)::
-* Traps Installing More Traps::
-* Common Trap Options::
-* Procedure Traps::
-* Exit Traps::
-* Entry Traps::
-* Apply Traps::
-* Step Traps::
-* Source Traps::
-* Location Traps::
-* Trap Shorthands::
-* Trap Utilities::
-@end menu
+@example
+(use-modules (system vm vm))
+@end example
+@noindent
+The result of calling @code{the-vm} is usually passed as the @var{vm}
+argument to all of these procedures.
-@node How to Set a Trap
-@subsubsection How to Set a Trap
+@deffn {Scheme Procedure} vm-next-hook vm
+The hook that will be fired before an instruction is retired (and
+executed).
+@end deffn
-@cindex Setting traps
-@cindex Installing and uninstalling traps
-Setting a trap is done in two parts. First the trap is defined by
-creating an instance of the appropriate trap class, with slot values
-specifying the condition under which the trap will fire and the action
-to take when it fires. Secondly the trap object thus created must be
-@dfn{installed}.
+@deffn {Scheme Procedure} vm-push-continuation-hook vm
+The hook that will be fired after preparing a new frame. Fires just
+before applying a procedure in a non-tail context, just before the
+corresponding apply-hook.
+@end deffn
-To make this immediately concrete, here is an example that sets a trap
-to fire on the next application of the @code{facti} procedure, and to
-handle the trap by entering the command line debugger.
+@deffn {Scheme Procedure} vm-pop-continuation-hook vm
+The hook that will be fired before returning from a frame.
-@lisp
-(install-trap (make <procedure-trap>
- #:procedure facti
- #:single-shot #t
- #:behaviour debug-trap))
-@end lisp
+This hook is a bit trickier than the rest, in that there is a particular
+interpretation of the values on the stack. Specifically, the top value
+on the stack is the number of values being returned, and the next
+@var{n} values are the actual values being returned, with the last value
+highest on the stack.
+@end deffn
-@noindent
-Briefly, the elements of this incantation are as follows. (All of
-these are described more fully in the following subsubsections.)
+@deffn {Scheme Procedure} vm-apply-hook vm
+The hook that will be fired before a procedure is applied. The frame's
+procedure will have already been set to the new procedure.
-@itemize @bullet
-@item
-@code{<procedure-trap>} is the trap class for trapping on invocation
-of a specific procedure.
+Note that procedure application is somewhat orthogonal to continuation
+pushes and pops. A non-tail call to a procedure will result first in a
+firing of the push-continuation hook, then this application hook,
+whereas a tail call will run without having fired a push-continuation
+hook.
+@end deffn
-@item
-@code{#:procedure facti} says that the specific procedure to trap on for this
-trap object is @code{facti}.
+@deffn {Scheme Procedure} vm-abort-continuation-hook vm
+The hook that will be called after aborting to a
+prompt. @xref{Prompts}. The stack will be in the same state as for
+@code{vm-pop-continuation-hook}.
+@end deffn
-@item
-@code{#:single-shot #t} says that this trap should only fire on the
-@emph{next} invocation of @code{facti}, not on all future invocations
-(which is the default if the @code{#:single-shot} option is not
-specified).
+@deffn {Scheme Procedure} vm-restore-continuation-hook vm
+The hook that will be called after restoring an undelimited
+continuation. Unfortunately it's not currently possible to introspect on
+the values that were given to the continuation.
+@end deffn
-@item
-@code{#:behaviour debug-trap} says that the trap infrastructure should
-call the procedure @code{debug-trap} when this trap fires.
+@cindex VM trace level
+These hooks do impose a performance penalty, if they are on. Obviously,
+the @code{vm-next-hook} has quite an impact, performance-wise. Therefore
+Guile exposes a single, heavy-handed knob to turn hooks on or off, the
+@dfn{VM trace level}. If the trace level is positive, hooks run;
+otherwise they don't.
-@item
-Finally, the @code{install-trap} call installs the trap immediately.
-@end itemize
+@deffn {Scheme Procedure} vm-trace-level vm
+Retrieve the ``trace level'' of the VM. If positive, the trace hooks
+associated with @var{vm} will be run. The initial trace level is 0.
+@end deffn
-@noindent
-It is of course possible for the user to define more convenient
-shorthands for setting common kinds of traps. @xref{Trap Shorthands},
-for some examples.
+@deffn {Scheme Procedure} set-vm-trace-level! vm level
+Set the ``trace level'' of the VM.
+@end deffn
+
+@xref{A Virtual Machine for Guile}, for more information on Guile's
+virtual machine.
+
+@node Trap Interface
+@subsubsection Trap Interface
+
+The capabilities provided by hooks are great, but hooks alone rarely
+correspond to what users want to do.
+
+For example, if a user wants to break when and if control reaches a
+certain source location, how do you do it? If you install a ``next''
+hook, you get unacceptable overhead for the execution of the entire
+program. It would be possible to install an ``apply'' hook, then if the
+procedure encompasses those source locations, install a ``next'' hook,
+but already you're talking about one concept that might be implemented
+by a varying number of lower-level concepts.
+
+It's best to be clear about things and define one abstraction for all
+such conditions: the @dfn{trap}.
+
+Considering the myriad capabilities offered by the hooks though, there
+is only a minimum of functionality shared by all traps. Guile's current
+take is to reduce this to the absolute minimum, and have the only
+standard interface of a trap be ``turn yourself on'' or ``turn yourself
+off''.
-The ability to install, uninstall and reinstall a trap without losing
-its definition is Guile's equivalent of the disable/enable commands
-provided by debuggers like GDB.
+This interface sounds a bit strange, but it is useful to procedurally
+compose higher-level traps from lower-level building blocks. For
+example, Guile defines a trap that calls one handler when control enters
+a procedure, and another when control leaves the procedure. Given that
+trap, one can define a trap that adds to the next-hook only when within
+a given procedure. Building further, one can define a trap that fires
+when control reaches particular instructions within a procedure.
+
+Or of course you can stop at any of these intermediate levels. For
+example, one might only be interested in calls to a given procedure. But
+the point is that a simple enable/disable interface is all the
+commonality that exists between the various kinds of traps, and
+furthermore that such an interface serves to allow ``higher-level''
+traps to be composed from more primitive ones.
+
+Specifically, a trap, in Guile, is a procedure. When a trap is created,
+by convention the trap is enabled; therefore, the procedure that is the
+trap will, when called, disable the trap, and return a procedure that
+will enable the trap, and so on.
+
+Trap procedures take one optional argument: the current frame. (A trap
+may want to add to different sets of hooks depending on the frame that
+is current at enable-time.)
+
+If this all sounds very complicated, it's because it is. Some of it is
+essential, but probably most of it is not. The advantage of using this
+minimal interface is that composability is more lexically apparent than
+when, for example, using a stateful interface based on GOOPS. But
+perhaps this reflects the cognitive limitations of the programmer who
+made the current interface more than anything else.
+
+@node Low-Level Traps
+@subsubsection Low-Level Traps
+
+@deffn {Scheme Procedure} trap-at-procedure-call proc handler @
+ [#:vm (the-vm)] [#:closure? #f]
+@end deffn
+
+
+@deffn {Scheme Procedure} trap-in-procedure proc @
+ enter-handler exit-handler @
+ [#:current-frame = #f] [#:vm = (the-vm)] [#:closure? = #f]
+A more complicated trap, traps when control enters a procedure.
+
+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.
-@deffn {Generic Function} install-trap trap
-Install the trap object @var{trap}, so that its behaviour will be
-executed when the conditions for the trap firing are met.
@end deffn
-@deffn {Generic Function} uninstall-trap trap
-Uninstall the trap object @var{trap}, so that its behaviour will
-@emph{not} be executed even if the conditions for the trap firing are
-met.
+@deffn {Scheme Procedure} trap-instructions-in-procedure proc @
+ next-handler exit-handler @
+ [#:current-frame = #f] [#:vm = (the-vm)] [#:closure? = #f]
+Building on trap-in-procedure, we have trap-instructions-in-procedure
@end deffn
+@deffn {Scheme Procedure} trap-at-procedure-ip-in-range proc range @
+ handler @
+ [#:current-frame = #f] [#:vm = (the-vm)] [#:closure? = #f]
+Building on trap-instructions-in-procedure, we have
+trap-at-procedure-ip-in-range.
+@end deffn
-@node Specifying Trap Behaviour
-@subsubsection Specifying Trap Behaviour
+@deffn {Scheme Procedure} trap-at-source-location file user-line handler @
+ [#:current-frame = #f] [#:vm = (the-vm)]
+Building on trap-on-instructions-in-procedure, we have
+trap-at-source-location. The parameter `user-line' is one-indexed, as
+a user counts lines, instead of zero-indexed, as Guile counts lines.
+@end deffn
-@cindex Trap behaviour
-Guile provides several ``out-of-the-box'' behaviours for common needs.
-All of the following can be used directly as the value of the
-@code{#:behaviour} option when creating a trap object.
+@deffn {Scheme Procedure} trap-frame-finish frame return-handler abort-handler @
+ [#:vm = (the-vm)]
+On a different tack, now we're going to build up a set of traps that
+do useful things during the dynamic extent of a procedure's
+application. First, a trap for when a frame returns.
+@end deffn
-@deffn {Procedure} debug-trap trap-context
-Enter Guile's command line debugger to explore the stack at
-@var{trap-context}, and to single-step or continue program execution
-from that point.
+@deffn {Scheme Procedure} trap-in-dynamic-extent proc @
+ enter-handler return-handler abort-handler @
+ [#:vm = (the-vm)] [#:closure? = #f]
+A more traditional dynamic-wind trap. Perhaps this should not be
+based on the above trap-frame-finish?
@end deffn
-@deffn {Procedure} gds-debug-trap trap-context
-Use the GDS debugging interface, which displays the stack and
-corresponding source code via Emacs, to explore the stack at
-@var{trap-context} and to single-step or continue program execution
-from that point.
+@deffn {Scheme Procedure} trap-calls-in-dynamic-extent proc @
+ apply-handler return-handler @
+ [#:current-frame = #f] [#:vm = (the-vm)] [#:closure? = #f]
+Trapping all procedure calls within a dynamic extent, recording the
+depth of the call stack relative to the original procedure.
@end deffn
-@cindex Trace
-@cindex Tracing
-@deffn {Procedure} trace-trap trap-context
-Display trace information to summarize the current @var{trap-context}.
+@deffn {Scheme Procedure} trap-instructions-in-dynamic-extent proc @
+ next-handler @
+ [#:current-frame = #f] [#:vm = (the-vm)] [#:closure? = #f]
+Trapping all retired intructions within a dynamic extent.
@end deffn
-@deffn {Procedure} trace-at-exit trap-context
-Install a further trap to cause the return value of the application or
-evaluation just starting (as described by @var{trap-context}) to be
-traced using @code{trace-trap}, when this application or evaluation
-completes. The extra trap is automatically uninstalled after the
-return value has been traced.
+@deffn {Scheme Procedure} trap-calls-to-procedure proc @
+ apply-handler return-handler @
+ [#:vm = (the-vm)]
+Traps calls and returns for a given procedure, keeping track of the call depth.
@end deffn
-@deffn {Procedure} trace-until-exit trap-context
-Install a further trap so that every step that the evaluator performs
-as part of the application or evaluation just starting (as described
-by @var{trap-context}) is traced using @code{trace-trap}. The extra
-trap is automatically uninstalled when the application or evaluation
-is complete. @code{trace-until-exit} can be very useful as a first
-step when all you know is that there is a bug ``somewhere in XXX or in
-something that XXX calls''.
+@deffn {Scheme Procedure} trap-matching-instructions frame-pred handler @
+ [#:vm = (the-vm)]
+Trap when the source location changes.
@end deffn
-@noindent
-@code{debug-trap} and @code{gds-debug-trap} are provided by the modules
-@code{(ice-9 debugger)} and @code{(ice-9 gds-client)} respectively, and
-their behaviours are fairly self-explanatory. For more information on
-the operation of the GDS interface via Emacs, see @ref{Using Guile in
-Emacs}. The tracing behaviours are explained more fully below.
+@node Tracing Traps
+@subsubsection Tracing Traps
+
+The @code{(system vm trace)} module defines a number of traps for
+tracing of procedure applications. When a procedure is @dfn{traced}, it
+means that every call to that procedure is reported to the user during a
+program run. The idea is that you can mark a collection of procedures
+for tracing, and Guile will subsequently print out a line of the form
+
+@lisp
+| | (@var{procedure} @var{args} @dots{})
+@end lisp
+
+whenever a marked procedure is about to be applied to its arguments.
+This can help a programmer determine whether a function is being called
+at the wrong time or with the wrong set of arguments.
-@cindex Trap context
-More generally, the @dfn{behaviour} specified for a trap can be any
-procedure that expects to be called with one @dfn{trap context}
-argument. A trivial example would be:
+In addition, the indentation of the output is useful for demonstrating
+how the traced applications are or are not tail recursive with respect
+to each other. Thus, a trace of a non-tail recursive factorial
+implementation looks like this:
@lisp
-(define (report-stack-depth trap-context)
- (display "Stack depth at the trap is: ")
- (display (tc:depth trap-context))
- (newline))
+scheme@@(guile-user)> (define (fact1 n)
+ (if (zero? n) 1
+ (* n (fact1 (1- n)))))
+scheme@@(guile-user)> ,trace (fact1 4)
+trace: (fact1 4)
+trace: | (fact1 3)
+trace: | | (fact1 2)
+trace: | | | (fact1 1)
+trace: | | | | (fact1 0)
+trace: | | | | 1
+trace: | | | 1
+trace: | | 2
+trace: | 6
+trace: 24
@end lisp
+While a typical tail recursive implementation would look more like this:
+
+@lisp
+scheme@@(guile-user)> (define (facti acc n)
+ (if (zero? n) acc
+ (facti (* n acc) (1- n))))
+scheme@@(guile-user)> (define (fact2 n) (facti 1 n))
+scheme@@(guile-user)> ,trace (fact2 4)
+trace: (fact2 4)
+trace: (facti 1 4)
+trace: (facti 4 3)
+trace: (facti 12 2)
+trace: (facti 24 1)
+trace: (facti 24 0)
+trace: 24
+@end lisp
+
+@deffn {Scheme Procedure} trace-calls-to-procedure proc #:key (width 80) (vm (the-vm)) (prefix "trace: "))
+@end deffn
+
+@deffn {Scheme Procedure} trace-calls-in-procedure proc #:key (width 80) (vm (the-vm)) (prefix "trace: "))
+@end deffn
+
+@deffn {Scheme Procedure} trace-instructions-in-procedure proc #:key (width 80) (vm (the-vm))
+@end deffn
+
+In addition, Guile defines a procedure to call a thunk, tracing all
+procedure calls and returns within the thunk.
+
+@deffn {Scheme Procedure} call-with-trace thunk #:key (calls? #t) (instructions? #f) (width 80) (vm (the-vm))
+Call @var{thunk}, tracing all execution within its dynamic extent.
+
+If @var{calls?} is true, Guile will print a brief report at each
+procedure call and return, as given above.
+
+If @var{instructions?} is true, Guile will also print a message each
+time an instruction is executed. This is a lot of output, but it is
+sometimes useful when doing low-level optimization.
+
+Note that because this procedure manipulates the VM trace level
+directly, it doesn't compose well with traps at the REPL.
+@end deffn
+
+@xref{Profile Commands}, for more information on tracing at the REPL.
+
+@node Trap States
+@subsubsection Trap States
+
+@deffn {Scheme Procedure} list-traps
+@end deffn
+
+@deffn {Scheme Procedure} trap-name idx
+@end deffn
-@node Trap Context
-@subsubsection Trap Context
+@deffn {Scheme Procedure} trap-enabled? idx
+@end deffn
-The @dfn{trap context} is an object that caches information about the
-low level trap call and the stack at the point of the trap, and is
-passed as the only argument to all behaviour procedures. The
-information in the trap context can be accessed through the procedures
-beginning @code{tc:} that are exported by the @code{(ice-9 debugging
-traps)} module@footnote{Plus of course any procedures that build on
-these, such as the @code{trace/@dots{}} procedures exported by
-@code{(ice-9 debugging trace)} (@pxref{Tracing Configuration}).}; the
-most useful of these are as follows.
+@deffn {Scheme Procedure} enable-trap! idx
+@end deffn
-@deffn {Generic Function} tc:type trap-context
-Indicates the type of the low level trap by returning one of the
-keywords @code{#:application}, @code{#:evaluation}, @code{#:return} or
-@code{#:error}.
+@deffn {Scheme Procedure} disable-trap! idx
@end deffn
-@deffn {Generic Function} tc:return-value trap-context
-When @code{tc:type} gives @code{#:return}, this provides the value
-that is being returned.
+@deffn {Scheme Procedure} delete-trap! idx
@end deffn
-@deffn {Generic Function} tc:stack trap-context
-Provides the stack at the point of the trap (as computed by
-@code{make-stack}, but cached so that the lengthy @code{make-stack}
-operation is not performed more than once for the same low level
-trap).
+@node Trap Handlers
+@subsubsection Trap Handlers
+
+Trap Handlers What to do when a trap in a trap state fires.
+
+@deffn {Scheme Procedure} with-default-trap-handler handler thunk
@end deffn
-@deffn {Generic Function} tc:frame trap-context
-The innermost frame of the stack at the point of the trap.
+@deffn {Scheme Procedure} install-trap-handler! handler
@end deffn
-@deffn {Generic Function} tc:depth trap-context
-The number of frames (including tail recursive non-real frames) in the
-stack at the point of the trap.
+@node Setting Traps
+@subsubsection Setting Traps
+
+@cindex Setting traps
+@cindex Installing and uninstalling traps
+Setting Traps The highest-level trap interface. Use this.
+
+@deffn {Scheme Procedure} add-trap-at-procedure-call! proc
@end deffn
-@deffn {Generic Function} tc:real-depth trap-context
-The number of real frames (that is, excluding the non-real frames that
-describe tail recursive calls) in the stack at the point of the trap.
+@deffn {Scheme Procedure} add-trace-at-procedure-call! proc
@end deffn
+@deffn {Scheme Procedure} add-trap-at-source-location! file user-line
+@end deffn
-@node Tracing Examples
-@subsubsection Tracing Examples
+;; handler := frame -> nothing
+@deffn {Scheme Procedure} add-ephemeral-trap-at-frame-finish! frame handler
+@end deffn
+
+@deffn {Scheme Procedure} add-ephemeral-stepping-trap! frame handler #:key (into? #t) (instruction? #f)
+@end deffn
+
+
+@node Debugging Examples
+@subsection Debugging Examples
+
+@c @node Tracing Examples
+@subsubheading Tracing Examples
The following examples show what tracing is and the kind of output that
it generates. In the first example, we define a recursive function for
in evaluating @code{(rev '(a b))}.
-@node Tracing Configuration
-@subsubsection Tracing Configuration
-
-The detail of what gets printed in each trace line, and the port to
-which tracing is written, can be configured by the procedures
-@code{set-trace-layout} and @code{trace-port}, both exported by the
-@code{(ice-9 debugging trace)} module.
-
-@deffn {Procedure with Setter} trace-port
-Get or set the port to which tracing is printed. The default is the
-value of @code{(current-output-port)} when the @code{(ice-9 debugging
-trace)} module is first loaded.
-@end deffn
-
-@deffn {Procedure} set-trace-layout format-string . arg-procs
-Layout each trace line using @var{format-string} and @var{arg-procs}.
-For each trace line, the list of values to be printed is obtained by
-calling all the @var{arg-procs}, passing the trap context as the only
-parameter to each one. This list of values is then formatted using
-the specified @var{format-string}.
-@end deffn
-
-@noindent
-The @code{(ice-9 debugging trace)} module exports a set of arg-proc
-procedures to cover most common needs, with names beginning
-@code{trace/}. These are all implemented on top of the @code{tc:} trap
-context accessor procedures documented in @ref{Trap Context}, and if any
-trace output not provided by the following is needed, it should be
-possible to implement based on a combination of the @code{tc:}
-procedures.
-
-@deffn {Procedure} trace/pid trap-context
-An arg-proc that returns the current process ID.
-@end deffn
-
-@deffn {Procedure} trace/stack-id trap-context
-An arg-proc that returns the stack ID of the stack in which the
-current trap occurred.
-@end deffn
-
-@deffn {Procedure} trace/stack-depth trap-context
-An arg-proc that returns the length (including non-real frames) of the
-stack at the point of the current trap.
-@end deffn
-
-@deffn {Procedure} trace/stack-real-depth trap-context
-An arg-proc that returns the length excluding non-real frames of the
-stack at the point of the current trap.
-@end deffn
-
-@deffn {Procedure} trace/stack trap-context
-An arg-proc that returns a string summarizing stack information. This
-string includes the stack ID, real depth, and count of additional
-non-real frames, with the format @code{"~a:~a+~a"}.
-@end deffn
-
-@deffn {Procedure} trace/source-file-name trap-context
-An arg-proc that returns the name of the source file for the innermost
-stack frame, or an empty string if source is not available for the
-innermost frame.
-@end deffn
-
-@deffn {Procedure} trace/source-line trap-context
-An arg-proc that returns the line number of the source code for the
-innermost stack frame, or zero if source is not available for the
-innermost frame.
-@end deffn
-
-@deffn {Procedure} trace/source-column trap-context
-An arg-proc that returns the column number of the start of the source
-code for the innermost stack frame, or zero if source is not available
-for the innermost frame.
-@end deffn
-
-@deffn {Procedure} trace/source trap-context
-An arg-proc that returns the source location for the innermost stack
-frame. This is a string composed of file name, line and column number
-with the format @code{"~a:~a:~a"}, or an empty string if source is not
-available for the innermost frame.
-@end deffn
-
-@deffn {Procedure} trace/type trap-context
-An arg-proc that returns a three letter abbreviation indicating the
-type of the current trap: @code{"APP"} for an application frame,
-@code{"EVA"} for an evaluation, @code{"RET"} for an exit trap, or
-@code{"ERR"} for an error (pseudo-)trap.
-@end deffn
-
-@deffn {Procedure} trace/real? trap-context
-An arg-proc that returns @code{" "} if the innermost stack frame is a
-real frame, or @code{"t"} if it is not.
-@end deffn
-
-@deffn {Procedure} trace/info trap-context
-An arg-proc that returns a string describing the expression being
-evaluated, application being performed, or return value, according to
-the current trap type.
-@end deffn
-
-@noindent
-@code{trace/stack-depth} and @code{trace/stack-real-depth} are identical
-to the trap context methods @code{tc:depth} and @code{tc:real-depth}
-described before (@pxref{Trap Context}), but renamed here for
-convenience.
-
-The default trace layout, as exhibited by the examples of the previous
-subsubsubsection, is set by this line of code from the @code{(ice-9 debugging
-traps)} module:
-
-@lisp
-(set-trace-layout "|~3@@a: ~a\n" trace/stack-real-depth trace/info)
-@end lisp
-
-@noindent
-If we rerun the first of those examples, but with trace layout
-configured to show source location and trap type in addition, the
-output looks like this:
-
-@lisp
-guile> (set-trace-layout "| ~25a ~3@@a: ~a ~a\n"
- trace/source
- trace/stack-real-depth
- trace/type
- trace/info)
-guile> (rev '(a b c))
-| standard input:29:0 2: APP [rev (a b c)]
-| standard input:4:21 3: APP [rev (b c)]
-| standard input:4:21 4: APP [rev (c)]
-| standard input:4:21 5: APP [rev ()]
-| standard input:2:9 5: RET =>()
-| standard input:4:13 4: RET =>(c)
-| standard input:4:13 3: RET =>(c b)
-| standard input:4:13 2: RET =>(c b a)
-(c b a)
-@end lisp
-
-
-@node Tracing and (ice-9 debug)
-@subsubsection Tracing and (ice-9 debug)
-
-The @code{(ice-9 debug)} module provides a tracing facility
-(@pxref{Tracing}) that is roughly similar to that described here, but
-there are important differences.
-
-@itemize @bullet
-@item
-The @code{(ice-9 debug)} trace gives a nice pictorial view of changes
-in stack depth, by using indentation like this:
-
-@lisp
-[fact1 4]
-| [fact1 3]
-| | [fact1 2]
-| | | [fact1 1]
-| | | | [fact1 0]
-| | | | 1
-| | | 1
-| | 2
-| 6
-24
-@end lisp
-
-However its output can @emph{only} show the information seen here,
-which corresponds to @code{(ice-9 debugging trace)}'s
-@code{trace/info} procedure; it cannot be configured to show other
-pieces of information about the trap context in the way that the
-@code{(ice-9 debugging trace)} implementation can.
-
-@item
-The @code{(ice-9 debug)} trace only allows the tracing of procedure
-applications and their return values, whereas the @code{(ice-9 debugging
-trace)} implementation allows any kind of trap to be traced.
-
-It's interesting to note that @code{(ice-9 debug)}'s restriction here,
-which might initially appear to be just a straightforward consequence
-of its implementation, is also somewhat dictated by its pictorial
-display. The use of indentation in the output relies on hooking into
-the low level trap calls in such a way that the trapped application
-entries and exits exactly balance each other. The @code{ice-9
-debugging trace} implementation allows traps to be installed such that
-entry and exit traps don't necessarily balance, which means that, in
-general, indentation diagrams like the one above don't work.
-@end itemize
-
-It isn't currently possible to use both @code{(ice-9 debug)} trace and
-@code{(ice-9 debugging trace)} in the same Guile session, because
-their settings of the low level trap options conflict with each other.
-
-
-@node Traps Installing More Traps
-@subsubsection Traps Installing More Traps
-
-Sometimes it is desirable for the behaviour at one trap to install
-further traps. In other words, the behaviour is something like
-``Don't do much right now, but set things up to stop after two or
-three more steps'', or ``@dots{} when this frame completes''. This is
-absolutely fine. For example, it is easy to code a generic ``do
-so-and-so when the current frame exits'' procedure, which can be used
-wherever a trap context is available, as follows.
-
-@lisp
-(define (at-exit trap-context behaviour)
- (install-trap (make <exit-trap>
- #:depth (tc:depth trap-context)
- #:single-shot #t
- #:behaviour behaviour)))
-@end lisp
-
-To continue and pin down the example, this could then be used as part
-of a behaviour whose purpose was to measure the accumulated time spent
-in and below a specified procedure.
-
-@lisp
-(define calls 0)
-(define total 0)
-
-(define accumulate-time
- (lambda (trap-context)
- (set! calls (+ calls 1))
- (let ((entry (current-time)))
- (at-exit trap-context
- (lambda (ignored)
- (set! total
- (+ total (- (current-time)
- entry))))))))
-
-(install-trap (make <procedure-trap>
- #:procedure my-proc
- #:behaviour accumulate-time))
-@end lisp
-
-
-@node Common Trap Options
-@subsubsection Common Trap Options
-
-When creating any kind of trap object, settings for the trap being
-created are specified as options on the @code{make} call using syntax
-like this:
-
-@lisp
-(make <@var{trap-class}>
- #:@var{option-keyword} @var{setting}
- @dots{})
-@end lisp
-
-The following common options are provided by the base class
-@code{<trap>}, and so can be specified for any kind of trap.
-
-@deffn {Class} <trap>
-Base class for trap objects.
-@end deffn
-
-@deffn {Trap Option} #:condition thunk
-If not @code{#f}, this is a thunk which is called when the trap fires,
-to determine whether trap processing should proceed any further. If
-the thunk returns @code{#f}, the trap is basically suppressed.
-Otherwise processing continues normally. (Default value @code{#f}.)
-@end deffn
-
-@deffn {Trap Option} #:skip-count count
-A count of valid (after @code{#:condition} processing) firings of this
-trap to skip. (Default value 0.)
-@end deffn
-
-@deffn {Trap Option} #:single-shot boolean
-If not @code{#f}, this indicates that the trap should be automatically
-uninstalled after it has successfully fired (after @code{#:condition}
-and @code{#:skip-count} processing) for the first time. (Default
-value @code{#f}.)
-@end deffn
-
-@deffn {Trap Option} #:behaviour behaviour-proc
-A trap behaviour procedure --- as discussed in the preceding subsubsection
---- or a list of such procedures, in which case each procedure is
-called in turn when the trap fires. (Default value @code{'()}.)
-@end deffn
-
-@deffn {Trap Option} #:repeat-identical-behaviour boolean
-Normally, if multiple trap objects are triggered by the same low level
-trap, and they request the same behaviour, it's only actually useful
-to do that behaviour once (per low level trap); so by default multiple
-requests for the same behaviour are coalesced. If this option is set
-other than @code{#f}, the contents of the @code{#:behaviour} option
-are uniquified so that they avoid being coalesced in this way.
-(Default value @code{#f}.)
-@end deffn
-
-
-@node Procedure Traps
-@subsubsection Procedure Traps
-
-The @code{<procedure-trap>} class implements traps that are triggered
-upon application of a specified procedure. Instances of this class
-should use the @code{#:procedure} option to specify the procedure to
-trap on.
-
-@deffn {Class} <procedure-trap>
-Class for traps triggered by application of a specified procedure.
-@end deffn
-
-@deffn {Trap Option} #:procedure procedure
-Specifies the procedure to trap on.
-@end deffn
-
-@noindent
-Example:
-
-@lisp
-(install-trap (make <procedure-trap>
- #:procedure my-proc
- #:behaviour (list trace-trap
- trace-until-exit)))
-@end lisp
-
-
-@node Exit Traps
-@subsubsection Exit Traps
-
-The @code{<exit-trap>} class implements traps that are triggered upon
-stack frame exit past a specified stack depth. Instances of this
-class should use the @code{#:depth} option to specify the target stack
-depth.
-
-@deffn {Class} <exit-trap>
-Class for traps triggered by exit past a specified stack depth.
-@end deffn
-
-@deffn {Trap Option} #:depth depth
-Specifies the reference depth for the trap.
-@end deffn
-
-@noindent
-Example:
-
-@lisp
-(define (trace-at-exit trap-context)
- (install-trap (make <exit-trap>
- #:depth (tc:depth trap-context)
- #:single-shot #t
- #:behaviour trace-trap)))
-@end lisp
-
-@noindent
-(This is the actual definition of the @code{trace-at-exit} behaviour.)
-
-
-@node Entry Traps
-@subsubsection Entry Traps
-
-The @code{<entry-trap>} class implements traps that are triggered upon
-any stack frame entry. No further parameters are needed to specify an
-instance of this class, so there are no class-specific trap options.
-Note that it remains possible to use the common trap options
-(@pxref{Common Trap Options}), for example to set a trap for the
-@var{n}th next frame entry.
-
-@deffn {Class} <entry-trap>
-Class for traps triggered by any stack frame entry.
-@end deffn
-
-@noindent
-Example:
-
-@lisp
-(install-trap (make <entry-trap>
- #:skip-count 5
- #:behaviour gds-debug-trap))
-@end lisp
-
-
-@node Apply Traps
-@subsubsection Apply Traps
-
-The @code{<apply-trap>} class implements traps that are triggered upon
-any procedure application. No further parameters are needed to
-specify an instance of this class, so there are no class-specific trap
-options. Note that it remains possible to use the common trap options
-(@pxref{Common Trap Options}), for example to set a trap for the next
-application where some condition is true.
-
-@deffn {Class} <apply-trap>
-Class for traps triggered by any procedure application.
-@end deffn
-
-@noindent
-Example:
-
-@lisp
-(install-trap (make <apply-trap>
- #:condition my-condition
- #:behaviour gds-debug-trap))
-@end lisp
-
-
-@node Step Traps
-@subsubsection Step Traps
-
-The @code{<step-trap>} class implements traps that do single-stepping
-through a program's execution. They come in two flavours, with and
-without a specified file name. If a file name is specified, the trap
-is triggered by the next evaluation, application or frame exit
-pertaining to source code from the specified file. If a file name is
-not specified, the trap is triggered by the next evaluation,
-application or frame exit from any file (or for code whose source
-location was not recorded), in other words by the next evaluator step
-of any kind.
-
-The design goal of the @code{<step-trap>} class is to match what a
-user would intuitively think of as single-stepping through their code,
-either through code in general (roughly corresponding to GDB's
-@code{step} command, for example), or through code from a particular
-source file (roughly corresponding to GDB's @code{next}). Therefore
-if you are using a step trap to single-step through code and finding
-its behaviour counter-intuitive, please report that so we can improve
-it.
-
-The implementation and options of the @code{<step-trap>} class are
-complicated by the fact that it is unreliable to determine whether a
-low level frame exit trap is applicable to a specified file by
-examining the details of the reported frame. This is a consequence of
-tail recursion, which has the effect that many frames can be removed
-from the stack at once, with only the outermost frame being reported
-by the low level trap call. The effects of this on the
-@code{<step-trap>} class are such as to require the introduction of
-the strange-looking @code{#:exit-depth} option, for the following
-reasons.
-
-@itemize @bullet
-@item
-When stopped at the start of an application or evaluation frame, and
-it is desired to continue execution until the next ``step'' in the same
-source file, that next step could be the start of a nested application
-or evaluation frame, or --- if the procedure definition is in a
-different file, for example --- it could be the exit from the current
-frame.
-
-@item
-Because of the effects of tail recursion noted above, the current
-frame exit possibility must be expressed as frame exit past a
-specified stack depth. When an instance of the @code{<step-trap>}
-class is installed from the context of an application or evaluation
-frame entry, the @code{#:exit-depth} option should be used to specify
-this stack depth.
-
-@item
-When stopped at a frame exit, on the other hand, we know that the next
-step must be an application or evaluation frame entry. In this
-context the @code{#:exit-depth} option is not needed and should be
-omitted or set to @code{#f}.
-@end itemize
-
-@noindent
-When a step trap is installed without @code{#:single-shot #t}, such
-that it keeps firing, the @code{<step-trap>} code automatically
-updates its idea of the @code{#:exit-depth} setting each time, so that
-the trap always fires correctly for the following step.
-
-@deffn {Class} <step-trap>
-Class for single-stepping traps.
-@end deffn
-
-@deffn {Trap Option} #:file-name name
-If not @code{#f}, this is a string containing the name of a source
-file, and restricts the step trap to evaluation steps within that
-source file. (Default value @code{#f}.)
-@end deffn
-
-@deffn {Trap Option} #:exit-depth depth
-If not @code{#f}, this is a positive integer implying that the next
-step may be frame exit past the stack depth @var{depth}. See the
-discussion above for more details. (Default value @code{#f}.)
-@end deffn
-
-@noindent
-Example:
-
-@lisp
-(install-trap (make <step-trap>
- #:file-name (frame-file-name
- (stack-ref stack index))
- #:exit-depth (- (stack-length stack)
- (stack-ref stack index))
- #:single-shot #t
- #:behaviour debug-trap))
-@end lisp
-
-
-@node Source Traps
-@subsubsection Source Traps
-
-The @code{<source-trap>} class implements traps that are attached to a
-precise source code expression, as read by the reader, and which fire
-each time that that expression is evaluated. These traps use a low
-level Guile feature which can mark individual expressions for
-trapping, and are relatively efficient. But it can be tricky to get
-at the source expression in the first place, and these traps are
-liable to become irrelevant if the procedure containing the expression
-is reevaluated; these issues are discussed further below.
-
-@deffn {Class} <source-trap>
-Class for traps triggered by evaluation of a specific Scheme
-expression.
-@end deffn
-
-@deffn {Trap Option} #:expression expr
-Specifies the Scheme expression to trap on.
-@end deffn
-
-@noindent
-Example:
-
-@lisp
-(display "Enter an expression: ")
-(let ((x (read)))
- (install-trap (make <source-trap>
- #:expression x
- #:behaviour (list trace-trap
- trace-at-exit)))
- (primitive-eval x))
-@print{}
-Enter an expression: (+ 1 2 3 4 5 6)
-| 3: (+ 1 2 3 4 5 6)
-| 3: =>21
-21
-@end lisp
-
-The key point here is that the expression specified by the
-@code{#:expression} option must be @emph{exactly} (i.e. @code{eq?} to)
-what is going to be evaluated later. It doesn't work, for example, to
-say @code{#:expression '(+ x 3)}, with the expectation that the trap
-will fire whenever evaluating any expression @code{(+ x 3)}.
-
-The @code{trap-here} macro can be used in source code to create and
-install a source trap correctly. Take for example the factorial
-function defined in the @code{(ice-9 debugging example-fns)} module:
-
-@lisp
-(define (fact1 n)
- (if (= n 0)
- 1
- (* n (fact1 (- n 1)))))
-@end lisp
-
-@noindent
-To set a source trap on a particular expression --- let's say the
-expression @code{(= n 0)} --- edit the code so that the expression is
-enclosed in a @code{trap-here} macro call like this:
-
-@lisp
-(define (fact1 n)
- (if (trap-here (= n 0) #:behaviour debug-trap)
- 1
- (* n (fact1 (- n 1)))))
-@end lisp
-
-@deffn {Macro} trap-here expression . trap-options
-Install a source trap with options @var{trap-options} on
-@var{expression}, then return with the whole call transformed to
-@code{(begin @var{expression})}.
-@end deffn
-
-Note that if the @code{trap-here} incantation is removed, and
-@code{fact1} then redefined by reloading its source file, the effect
-of the source trap is lost, because the text ``(= n 0)'' is read again
-from scratch and becomes a new expression @code{(= n 0)} which does
-not have the ``trap here'' mark on it.
-
-If the semantics and setting of source traps seem unwieldy, location
-traps may meet your need more closely; these are described in the
-following subsubsection.
-
-
-@node Location Traps
-@subsubsection Location Traps
-
-The @code{<location-trap>} class implements traps that are triggered
-by evaluation of code at a specific source location. When compared
-with source traps, they are easier to set, and do not become
-irrelevant when the relevant code is reloaded; but unfortunately they
-are a lot less efficient, as they require running some ``are we in the
-right place for a trap'' code on every low level frame entry trap
-call.
-
-@deffn {Class} <location-trap>
-Class for traps triggered by evaluation of code at a specific source
-location.
-@end deffn
-
-@deffn {Trap Option} #:file-regexp regexp
-A regular expression specifying the filenames that will match this
-trap. This option must be specified when creating a location trap.
-@end deffn
-
-@deffn {Trap Option} #:line line
-The line number (0-based) of the source location at which the trap
-should be triggered. This option must be specified when creating a
-location trap.
-@end deffn
-
-@deffn {Trap Option} #:column column
-The column number (0-based) of the source location at which the trap
-should be triggered. This option must be specified when creating a
-location trap.
-@end deffn
-
-@noindent
-Here is an example, which matches the @code{(facti (- n 1) (* a n))}
-expression in @file{ice-9/debugging/example-fns.scm}:
-
-@lisp
-(install-trap (make <location-trap>
- #:file-regexp "example-fns.scm"
- #:line 11
- #:column 6
- #:behaviour gds-debug-trap))
-@end lisp
-
-
-@node Trap Shorthands
-@subsubsection Trap Shorthands
-
-If the code described in the preceding subsubsections for creating and
-manipulating traps seems a little long-winded, it is of course
-possible to define more convenient shorthand forms for typical usage
-patterns. Here are some examples.
-
-@lisp
-(define (break! proc)
- (install-trap (make <procedure-trap>
- #:procedure proc
- #:behaviour gds-debug-trap)))
-
-(define (trace! proc)
- (install-trap (make <procedure-trap>
- #:procedure proc
- #:behaviour (list trace-trap
- trace-at-exit))))
-
-(define (trace-subtree! proc)
- (install-trap (make <procedure-trap>
- #:procedure proc
- #:behaviour (list trace-trap
- trace-until-exit))))
-@end lisp
-
-Definitions like these are not provided out-of-the-box by Guile,
-because different users will have different ideas about what their
-default debugger should be, or, for example, which of the common trap
-options (@pxref{Common Trap Options}) it might be useful to expose
-through such shorthand procedures.
-
-
-@node Trap Utilities
-@subsubsection Trap Utilities
-
-@code{list-traps} can be used to print a description of all known trap
-objects. This uses a weak value hash table, keyed by a trap index
-number. Each trap object has its index number assigned, and is added
-to the hash table, when it is created by a @code{make @var{trap-class}
-@dots{}} call. When a trap object is GC'd, it is automatically
-removed from the hash table, and so no longer appears in the output
-from @code{list-traps}.
-
-@deffn {Variable} all-traps
-Weak value hash table containing all known trap objects.
-@end deffn
-
-@deffn {Procedure} list-traps
-Print a description of all known trap objects.
-@end deffn
-
-The following example shows a single trap that traces applications of
-the procedure @code{facti}.
-
-@lisp
-guile> (list-traps)
-#<<procedure-trap> 100d2e30> is an instance of class <procedure-trap>
-Slots are:
- number = 1
- installed = #t
- condition = #f
- skip-count = 0
- single-shot = #f
- behaviour = (#<procedure trace-trap (trap-context)>)
- repeat-identical-behaviour = #f
- procedure = #<procedure facti (n a)>
-@end lisp
-
-When @code{all-traps} or @code{list-traps} reveals a trap that you
-want to modify but no longer have a reference to, you can retrieve the
-trap object by calling @code{get-trap} with the trap's number. For
-example, here's how you could change the behaviour of the trap listed
-just above.
-
-@lisp
-(slot-set! (get-trap 1) 'behaviour (list debug-trap))
-@end lisp
-
-@deffn {Procedure} get-trap number
-Return the trap object with the specified @var{number}, or @code{#f}
-if there isn't one.
-@end deffn
-
-
-@node Debugging Examples
-@subsection Debugging Examples
-
Here we present some examples of what you can do with the debugging
facilities just described.
-@menu
-* Single Stepping through a Procedure's Code::
-* Profiling or Tracing a Procedure's Code::
-@end menu
-
-
-@node Single Stepping through a Procedure's Code
-@subsubsection Single Stepping through a Procedure's Code
+@subsubheading Single Stepping through a Procedure's Code
A good way to explore in detail what a Scheme procedure does is to set
a trap on it and then single step through what it does. To do this,
Guile command line.
-@node Profiling or Tracing a Procedure's Code
-@subsubsection Profiling or Tracing a Procedure's Code
+@subsubheading Profiling or Tracing a Procedure's Code
What if you wanted to get a trace of everything that the Guile
evaluator does within a given procedure, but without Guile stopping
HCoop / bpt / guile.git / commitdiff