summaryrefslogtreecommitdiff
path: root/doc/ref/api-control.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2016-12-12 20:55:08 +0100
committerAndy Wingo <wingo@pobox.com>2016-12-12 21:13:00 +0100
commit6dd87f4d8c764360c8d22c03f65603ea8b8c9e78 (patch)
tree6a502663cd206f0b4a46f61e8eb090ba4bd2e78b /doc/ref/api-control.texi
parentbf4a97898beac167e8b4f565ce4c7540bed24685 (diff)
downloadguile-6dd87f4d8c764360c8d22c03f65603ea8b8c9e78.tar.gz
Add suspendable-continuation?
* doc/ref/api-control.texi (Prompt Primitives): Document suspendable-continuation?. * libguile/control.c (scm_suspendable_continuation_p): New procedure. (scm_init_ice_9_control): New extension procedure, defines suspendable-continuation?. (scm_init_control): Register scm_init_ice_9_control. * libguile/eval.c (eval): * libguile/throw.c (catch): * libguile/continuations.c (scm_i_make_continuation): Restore resumable prompt cookie after continuation invocation. * libguile/vm.c (scm_call_n): Arrange to set resumable_prompt_cookie during invocation of VM. * libguile/vm.h (struct scm_vm): Add resumable_prompt_cookie member. * module/ice-9/control.scm: Export suspendable-continuation?. * test-suite/tests/control.test ("suspendable-continuation?"): New test.
Diffstat (limited to 'doc/ref/api-control.texi')
-rw-r--r--doc/ref/api-control.texi27
1 files changed, 27 insertions, 0 deletions
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index f0ded98a2..73fbe3607 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -628,6 +628,33 @@ This is equivalent to
@code{(call/ec (lambda (@var{k}) @var{body} @dots{}))}.
@end deffn
+Additionally there is another helper primitive exported by @code{(ice-9
+control)}, so load up that module for @code{suspendable-continuation?}:
+
+@example
+(use-modules (ice-9 control))
+@end example
+
+@deffn {Scheme Procedure} suspendable-continuation? tag
+Return @code{#t} if a call to @code{abort-to-prompt} with the prompt tag
+@var{tag} would produce a delimited continuation that could be resumed
+later.
+
+Almost all continuations have this property. The exception is where
+some code between the @code{call-with-prompt} and the
+@code{abort-to-prompt} recursed through C for some reason, the
+@code{abort-to-prompt} will succeed but any attempt to resume the
+continuation (by calling it) would fail. This is because composing a
+saved continuation with the current continuation involves relocating the
+stack frames that were saved from the old stack onto a (possibly) new
+position on the new stack, and Guile can only do this for stack frames
+that it created for Scheme code, not stack frames created by the C
+compiler. It's a bit gnarly but if you stick with Scheme, you won't
+have any problem.
+
+If no prompt is found with the given tag, this procedure just returns
+@code{#f}.
+@end deffn
@node Shift and Reset
@subsubsection Shift, Reset, and All That