diff options
author | Mark H Weaver <mhw@netris.org> | 2013-04-14 02:48:33 -0400 |
---|---|---|
committer | Mark H Weaver <mhw@netris.org> | 2013-04-14 02:48:33 -0400 |
commit | f6f4feb0a2222efcb297e634603621126542e63f (patch) | |
tree | 0b590c025f688ab625827c4f692fa7783716b558 /doc/ref/api-control.texi | |
parent | 1e051065628a7f1bd4398fcc11cd181f86084629 (diff) | |
parent | f5b2eea6a39507ecf6a8ecc62cc1c796c45c2d1d (diff) | |
download | guile-f6f4feb0a2222efcb297e634603621126542e63f.tar.gz |
Merge remote-tracking branch 'origin/stable-2.0'
Conflicts:
GUILE-VERSION
libguile/array-map.c
libguile/fports.h
libguile/gc.h
libguile/inline.h
libguile/ports.c
libguile/ports.h
libguile/print.c
libguile/r6rs-ports.c
libguile/read.c
test-suite/tests/00-socket.test
Diffstat (limited to 'doc/ref/api-control.texi')
-rw-r--r-- | doc/ref/api-control.texi | 56 |
1 files changed, 55 insertions, 1 deletions
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index 4dede7260..f34074ec6 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -577,9 +577,58 @@ 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}. A common +use of escape continuations is when throwing an exception +(@pxref{Exceptions}). + +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 @@ -987,6 +1036,11 @@ to avoid the risk of confusion with POSIX signals. This manual prefers to speak of throwing and catching exceptions, since this terminology matches the corresponding Guile primitives. +The exception mechanism described in this section has connections with +@dfn{delimited continuations} (@pxref{Prompts}). In particular, +throwing an exception is akin to invoking an @dfn{escape continuation} +(@pxref{Prompt Primitives, @code{call/ec}}). + @node Catch @subsubsection Catching Exceptions |