summaryrefslogtreecommitdiff
path: root/doc/ref/api-control.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2017-02-07 09:28:39 +0100
committerAndy Wingo <wingo@pobox.com>2017-02-07 09:57:55 +0100
commit498f3f95684361f3591106a8f9cb9065fd649288 (patch)
tree70a8e33d1ea25c54c273a3cbe347010403dfb07c /doc/ref/api-control.texi
parent81e9a128c146ccd495846ecbf664b3fd2855baf1 (diff)
downloadguile-498f3f95684361f3591106a8f9cb9065fd649288.tar.gz
Avoid stacks in dynamically-bound values
* libguile/dynstack.h: * libguile/dynstack.c (scm_dynstack_find_old_fluid_value): New function. * libguile/fluids.c (saved_dynamic_state_ref): New helper. (scm_fluid_ref): Fix docstring. (scm_fluid_ref_star): New function allowing access to previous values for a fluid. (scm_dynamic_state_ref): New internal function. * libguile/fluids.h: Add scm_fluid_ref_star and scm_dynamic_state_ref. * libguile/stacks.c (scm_stack_id): Adapt to %stacks not being a chain. * libguile/throw.c (catch, throw_without_pre_unwind): Adapt to %exception-handlers not being a chain. * module/ice-9/boot-9.scm (catch, dispatch-exception): Instead of having %exception-handlers be a chain, use fluid-ref* to access the chain that is in place at the time the exception is thrown. Prevents unintended undelimited capture of the current exception handler stack by a delimited "catch". (%start-stack): Similarly, don't be a chain. * module/system/repl/debug.scm (frame->stack-vector): * module/system/repl/error-handling.scm (call-with-error-handling): * module/ice-9/save-stack.scm (save-stack): Adapt to %stacks not being a chain. * test-suite/tests/exceptions.test ("delimited exception handlers"): Add tests. * doc/ref/api-control.texi (Fluids and Dynamic States): Add docs.
Diffstat (limited to 'doc/ref/api-control.texi')
-rw-r--r--doc/ref/api-control.texi15
1 files changed, 15 insertions, 0 deletions
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 73fbe3607..77d98b44e 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -1765,6 +1765,21 @@ a runtime error.
Set the value associated with @var{fluid} in the current dynamic root.
@end deffn
+@deffn {Scheme Procedure} fluid-ref* fluid depth
+@deffnx {C Function} scm_fluid_ref_star (fluid, depth)
+Return the @var{depth}th oldest value associated with @var{fluid} in the
+current thread. If @var{depth} equals or exceeds the number of values
+that have been assigned to @var{fluid}, return the default value of the
+fluid. @code{(fluid-ref* f 0)} is equivalent to @code{(fluid-ref f)}.
+
+@code{fluid-ref*} is useful when you want to maintain a stack-like
+structure in a fluid, such as the stack of current exception handlers.
+Using @code{fluid-ref*} instead of an explicit stack allows any partial
+continuation captured by @code{call-with-prompt} to only capture the
+bindings made within the limits of the prompt instead of the entire
+continuation. @xref{Prompts}, for more on delimited continuations.
+@end deffn
+
@deffn {Scheme Procedure} fluid-unset! fluid
@deffnx {C Function} scm_fluid_unset_x (fluid)
Disassociate the given fluid from any value, making it unbound.