summaryrefslogtreecommitdiff
path: root/doc/ref/api-control.texi
diff options
context:
space:
mode:
authorMark H Weaver <mhw@netris.org>2013-04-14 02:48:33 -0400
committerMark H Weaver <mhw@netris.org>2013-04-14 02:48:33 -0400
commitf6f4feb0a2222efcb297e634603621126542e63f (patch)
tree0b590c025f688ab625827c4f692fa7783716b558 /doc/ref/api-control.texi
parent1e051065628a7f1bd4398fcc11cd181f86084629 (diff)
parentf5b2eea6a39507ecf6a8ecc62cc1c796c45c2d1d (diff)
downloadguile-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.texi56
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