summaryrefslogtreecommitdiff
path: root/doc/ref/api-debug.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2010-10-08 00:00:16 +0200
committerAndy Wingo <wingo@pobox.com>2010-10-08 00:00:16 +0200
commit63e36ea6da6e8e9599c18a6235617283c4c7832f (patch)
treed30046d2f28e748560b68b894d2a0ac9ecaafa8c /doc/ref/api-debug.texi
parent3b541ca244459492592c65d94d46bf7489da1ce0 (diff)
downloadguile-63e36ea6da6e8e9599c18a6235617283c4c7832f.tar.gz
finish traps documentation
* doc/ref/api-debug.texi (Low-Level Traps, Tracing Traps, Trap States): Add notes on using modules. (High-Level Traps): Combine "Trap Handlers" and "Setting Traps" here. Flesh out docs.
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r--doc/ref/api-debug.texi117
1 files changed, 102 insertions, 15 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index b3c7e6564..709da3fb2 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -746,8 +746,7 @@ understanding how the interface hangs together.
* 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.
+* High-Level Traps:: The highest-level trap interface. Use this.
@end menu
@@ -944,6 +943,13 @@ this argument gives the current frame that the trap is running in.
Defaults to @code{#f}.
@end table
+To have access to these procedures, you'll need to have imported the
+@code{(system vm traps)} module:
+
+@lisp
+(use-modules (system vm traps))
+@end lisp
+
@deffn {Scheme Procedure} trap-at-procedure-call proc handler @
[#:vm] [#:closure?]
A trap that calls @var{handler} when @var{proc} is applied.
@@ -1115,6 +1121,13 @@ A string to print out before each trace line. As seen above in the
examples, defaults to @code{"trace: "}.
@end table
+To have access to these procedures, you'll need to have imported the
+@code{(system vm trace)} module:
+
+@lisp
+(use-modules (system vm trace))
+@end lisp
+
@deffn {Scheme Procedure} trace-calls-to-procedure proc @
[#:width] [#:vm] [#:prefix]
Print a trace at applications of and returns from @var{proc}.
@@ -1165,12 +1178,18 @@ dynamic environment.
Traps identified by integers. A trap can be enabled, disabled, or
removed, and can have an associated user-visible name.
+These procedures have their own module:
+
+@lisp
+(use-modules (system vm trap-state))
+@end lisp
+
@deffn {Scheme Procedure} add-trap! trap name
Add a trap to the current trap state, associating the given @var{name}
with it. Returns a fresh trap identifier (an integer).
-Note that usually the more specific functions detailed in @ref{Setting
-Traps} are used in preference to this one.
+Note that usually the more specific functions detailed in
+@ref{High-Level Traps} are used in preference to this one.
@end deffn
@deffn {Scheme Procedure} list-traps
@@ -1200,38 +1219,106 @@ Disables trap @var{idx}.
Removes trap @var{idx}, disabling it first, if necessary.
@end deffn
-@node Trap Handlers
-@subsubsection Trap Handlers
+@node High-Level Traps
+@subsubsection High-Level Traps
+
+The low-level trap API allows one to make traps that call procedures,
+and the trap state API allows one to keep track of what traps are
+there. But neither of these APIs directly helps you when you want to
+set a breakpoint, because it's unclear what to do when the trap fires.
+Do you enter a debugger, or mail a summary of the situation to your
+great-aunt, or what?
+
+So for the common case in which you just want to install breakpoints,
+and then have them all result in calls one parameterizable procedure, we
+have the high-level trap interface.
+
+Perhaps we should have started this section with this interface, as it's
+clearly the one most people should use. But as its capabilities and
+limitations proceed from the lower layers, we felt that the
+character-building exercise of building a mental model could be useful.
-Trap Handlers What to do when a trap in a trap state fires.
+These procedures share a module with trap states:
+
+@lisp
+(use-modules (system vm trap-state))
+@end lisp
@deffn {Scheme Procedure} with-default-trap-handler handler thunk
+Call @var{thunk} in a dynamic context in which @var{handler} is the
+current trap handler.
+
+Additionally, during the execution of @var{thunk}, the VM trace level
+(@pxref{VM Hooks}) is set to the number of enabled traps. This ensures
+that traps will in fact fire.
+
+@var{handler} may be @code{#f}, in which case VM hooks are not enabled
+as they otherwise would be, as there is nothing to handle the traps.
@end deffn
+The trace-level-setting behavior of @code{with-default-trap-handler} is
+one of its more useful aspects, but if you are willing to forgo that,
+and just want to install a global trap handler, there's a function for
+that too:
+
@deffn {Scheme Procedure} install-trap-handler! handler
+Set the current thread's trap handler to @var{handler}.
@end deffn
-@node Setting Traps
-@subsubsection Setting Traps
-
-@cindex Setting traps
-@cindex Installing and uninstalling traps
-Setting Traps The highest-level trap interface. Use this.
+Trap handlers are called when traps installed by procedures from this
+module fire. The current ``consumer'' of this API is Guile's REPL, but
+one might easily imagine other trap handlers being used to integrate
+with other debugging tools.
+@cindex Breakpoints
+@cindex Setting breakpoints
@deffn {Scheme Procedure} add-trap-at-procedure-call! proc
+Install a trap that will fire when @var{proc} is called.
+
+This is a breakpoint.
@end deffn
+@cindex Tracepoints
+@cindex Setting tracepoints
@deffn {Scheme Procedure} add-trace-at-procedure-call! proc
+Install a trap that will print a tracing message when @var{proc} is
+called. @xref{Tracing Traps}, for more information.
+
+This is a tracepoint.
@end deffn
@deffn {Scheme Procedure} add-trap-at-source-location! file user-line
+Install a trap that will fire when control reaches the given source
+location. @var{user-line} is one-indexed, as users count lines, instead
+of zero-indexed, as Guile counts lines.
+
+This is a source breakpoint.
@end deffn
-;; handler := frame -> nothing
@deffn {Scheme Procedure} add-ephemeral-trap-at-frame-finish! frame handler
+Install a trap that will call @var{handler} when @var{frame} finishes
+executing. The trap will be removed from the trap state after firing, or
+on nonlocal exit.
+
+This is a finish trap, used to implement the ``finish'' REPL command.
@end deffn
-@deffn {Scheme Procedure} add-ephemeral-stepping-trap! frame handler #:key (into? #t) (instruction? #f)
+@deffn {Scheme Procedure} add-ephemeral-stepping-trap! frame handler [#:into?] [#:instruction?]
+Install a trap that will call @var{handler} after stepping to a
+different source line or instruction. The trap will be removed from the
+trap state after firing, or on nonlocal exit.
+
+If @var{instruction?} is false (the default), the trap will fire when
+control reaches a new source line. Otherwise it will fire when control
+reaches a new instruction.
+
+Additionally, if @var{into?} is false (not the default), the trap will
+only fire for frames at or prior to the given frame. If @var{into?} is
+true (the default), the trap may step into nested procedure
+invocations.
+
+This is a stepping trap, used to implement the ``step'', ``next'',
+``step-instruction'', and ``next-instruction'' REPL commands.
@end deffn