summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/api-debug.texi29
-rw-r--r--module/system/vm/trap-state.scm3
2 files changed, 31 insertions, 1 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
diff --git a/module/system/vm/trap-state.scm b/module/system/vm/trap-state.scm
index e9a2ad86c..435039aec 100644
--- a/module/system/vm/trap-state.scm
+++ b/module/system/vm/trap-state.scm
@@ -28,7 +28,8 @@
#:use-module (system vm trace)
#:use-module (system vm frame)
#:use-module (system vm program)
- #:export (list-traps
+ #:export (add-trap!
+ list-traps
trap-enabled?
trap-name
enable-trap!