diff options
author | Ludovic Courtès <ludo@gnu.org> | 2013-04-04 14:14:25 +0800 |
---|---|---|
committer | Ludovic Courtès <ludo@gnu.org> | 2013-04-05 22:54:14 +0200 |
commit | 55e26a49dbc5fa7ccbf218305d88b0b37db4db3f (patch) | |
tree | 39c618a29dc54a15d5c5c757430d89c01071886b /doc/ref/api-control.texi | |
parent | d888b531681c8528a2daafe0bea70c0a42313da6 (diff) | |
download | guile-55e26a49dbc5fa7ccbf218305d88b0b37db4db3f.tar.gz |
Add `call/ec' and `let/ec'.
Based on a patch by Nala Ginrut <nalaginrut@gmail.com>,
with suggestions from Mark H. Weaver.
* module/ice-9/control.scm (call-with-escape-continuation, call/ec): New
procedures.
(let-escape-continuation, let/ec): New macros.
* module/ice-9/futures.scm (let/ec): Remove.
* test-suite/tests/control.test ("escape-only continuations")["call/ec",
"let/ec"]: New tests.
* doc/ref/api-control.texi (Prompt Primitives): Document `call/ec',
`let/ec', and their long names.
Diffstat (limited to 'doc/ref/api-control.texi')
-rw-r--r-- | doc/ref/api-control.texi | 49 |
1 files changed, 48 insertions, 1 deletions
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index 320812dfb..278a03dcb 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -574,9 +574,56 @@ both. Before moving on, we should mention that if the handler of a prompt is a @code{lambda} expression, and the first argument isn't referenced, an abort to -that prompt will not cause a continuation to be reified. This can be an +that prompt will not cause a continuation to be reified. This can be an important efficiency consideration to keep in mind. +@cindex continuation, escape +One example where this optimization matters is @dfn{escape +continuations}. Escape continuations are delimited continuations whose +only use is to make a non-local exit---i.e., to escape from the current +continuation. Such continuations are invoked only once, and for this +reason they are sometimes called @dfn{one-shot continuations}. + +The constructs below are syntactic sugar atop prompts to simplify the +use of escape continuations. + +@deffn {Scheme Procedure} call-with-escape-continuation proc +@deffnx {Scheme Procedure} call/ec proc +Call @var{proc} with an escape continuation. + +In the example below, the @var{return} continuation is used to escape +the continuation of the call to @code{fold}. + +@lisp +(use-modules (ice-9 control) + (srfi srfi-1)) + +(define (prefix x lst) + ;; Return all the elements before the first occurrence + ;; of X in LST. + (call/ec + (lambda (return) + (fold (lambda (element prefix) + (if (equal? element x) + (return (reverse prefix)) ; escape `fold' + (cons element prefix))) + '() + lst)))) + +(prefix 'a '(0 1 2 a 3 4 5)) +@result{} (0 1 2) +@end lisp +@end deffn + +@deffn {Scheme Syntax} let-escape-continuation k body @dots{} +@deffnx {Scheme Syntax} let/ec k body @dots{} +Bind @var{k} within @var{body} to an escape continuation. + +This is equivalent to +@code{(call/ec (lambda (@var{k}) @var{body} @dots{}))}. +@end deffn + + @node Shift and Reset @subsubsection Shift, Reset, and All That |