summaryrefslogtreecommitdiff
path: root/doc/ref/api-debug.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2010-10-07 22:50:33 +0200
committerAndy Wingo <wingo@pobox.com>2010-10-07 22:50:33 +0200
commitde03880abeb1e91c5d4dffaaa0d26a5ee4e94e8e (patch)
tree9bbb72c6ad45bdd6f71790bc4ffcce0865c281e1 /doc/ref/api-debug.texi
parent90729e71055f5c763bbcef500a548bf1786b6743 (diff)
downloadguile-de03880abeb1e91c5d4dffaaa0d26a5ee4e94e8e.tar.gz
document trap states
* module/system/vm/trap-state.scm: Export add-trap!. * doc/ref/api-debug.texi (Trap States): Document.
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r--doc/ref/api-debug.texi29
1 files changed, 29 insertions, 0 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index c577ca46d..e6fbc7893 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -1154,22 +1154,51 @@ directly, it doesn't compose well with traps at the REPL.
@node Trap States
@subsubsection Trap States
+When multiple traps are present in a system, we begin to have a
+bookkeeping problem. How are they named? How does one disable, enable,
+or delete them?
+
+Guile's answer to this is to keep an implicit per-thread @dfn{trap
+state}. The trap state object is not exposed to the user; rather, API
+that works on trap states fetches the current trap state from the
+dynamic environment.
+
+Traps identified by integers. A trap can be enabled, disabled, or
+removed, and can have an associated user-visible name.
+
+@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.
+@end deffn
+
@deffn {Scheme Procedure} list-traps
+List the current set of traps, both enabled and disabled. Returns a list
+of integers.
@end deffn
@deffn {Scheme Procedure} trap-name idx
+Returns the name associated with trap @var{idx}, or @code{#f} if there
+is no such trap.
@end deffn
@deffn {Scheme Procedure} trap-enabled? idx
+Returns @code{#t} if trap @var{idx} is present and enabled, or @code{#f}
+otherwise.
@end deffn
@deffn {Scheme Procedure} enable-trap! idx
+Enables trap @var{idx}.
@end deffn
@deffn {Scheme Procedure} disable-trap! idx
+Disables trap @var{idx}.
@end deffn
@deffn {Scheme Procedure} delete-trap! idx
+Removes trap @var{idx}, disabling it first, if necessary.
@end deffn
@node Trap Handlers