update news; ready for 1.9.3

[bpt/guile.git] / doc / ref / api-control.texi

diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index dbb51cf..66fb99e 100644 (file)
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -22,6 +22,7 @@ flow of Scheme affects C code.
 * Error Reporting::             Procedures for signaling errors.
 * Dynamic Wind::                Dealing with non-local entrance/exit.
 * Handling Errors::             How to handle errors in C code.
+* Continuation Barriers::       Protection from non-local control flow.
 @end menu
 
 @node begin
@@ -1164,7 +1165,7 @@ lexical variables, this will be, well, inconvenient.
 
 Therefore, Guile offers the functions @code{scm_dynwind_begin} and
 @code{scm_dynwind_end} to delimit a dynamic extent.  Within this
-dynamic extent, which is calles a @dfn{dynwind context}, you can
+dynamic extent, which is called a @dfn{dynwind context}, you can
 perform various @dfn{dynwind actions} that control what happens when
 the dynwind context is entered or left.  For example, you can register
 a cleanup routine with @code{scm_dynwind_unwind_handler} that is
@@ -1234,28 +1235,29 @@ non-locally, @var{out_guard} is called.  If the dynamic extent of
 the dynamic-wind is re-entered, @var{in_guard} is called.  Thus
 @var{in_guard} and @var{out_guard} may be called any number of
 times.
+
 @lisp
 (define x 'normal-binding)
 @result{} x
-(define a-cont  (call-with-current-continuation
-                  (lambda (escape)
-                     (let ((old-x x))
-                       (dynamic-wind
-                          ;; in-guard:
-                          ;;
-                          (lambda () (set! x 'special-binding))
-
-                          ;; thunk
-                          ;;
-                          (lambda () (display x) (newline)
-                                     (call-with-current-continuation escape)
-                                     (display x) (newline)
-                                     x)
-
-                          ;; out-guard:
-                          ;;
-                          (lambda () (set! x old-x)))))))
-
+(define a-cont
+  (call-with-current-continuation
+   (lambda (escape)
+     (let ((old-x x))
+       (dynamic-wind
+           ;; in-guard:
+           ;;
+           (lambda () (set! x 'special-binding))
+
+           ;; thunk
+           ;;
+           (lambda () (display x) (newline)
+                      (call-with-current-continuation escape)
+                      (display x) (newline)
+                      x)
+
+           ;; out-guard:
+           ;;
+           (lambda () (set! x old-x)))))))
 ;; Prints:
 special-binding
 ;; Evaluates to:
@@ -1475,7 +1477,7 @@ In the following C functions, @var{SUBR} and @var{MESSAGE} parameters
 can be @code{NULL} to give the effect of @code{#f} described above.
 
 @deftypefn {C Function} SCM scm_error (SCM @var{key}, char *@var{subr}, char *@var{message}, SCM @var{args}, SCM @var{rest})
-Throw an error, as per @code{scm-error} above.
+Throw an error, as per @code{scm-error} (@pxref{Error Reporting}).
 @end deftypefn
 
 @deftypefn {C Function} void scm_syserror (char *@var{subr})
@@ -1500,6 +1502,33 @@ which is the name of the procedure incorrectly invoked.
 @end deftypefn
 
 
+@node Continuation Barriers
+@subsection Continuation Barriers
+
+The non-local flow of control caused by continuations might sometimes
+not be wanted. You can use @code{with-continuation-barrier} to erect
+fences that continuations can not pass.
+
+@deffn {Scheme Procedure} with-continuation-barrier proc
+@deffnx {C Function} scm_with_continuation_barrier (proc)
+Call @var{proc} and return its result.  Do not allow the invocation of
+continuations that would leave or enter the dynamic extent of the call
+to @code{with-continuation-barrier}.  Such an attempt causes an error
+to be signaled.
+
+Throws (such as errors) that are not caught from within @var{proc} are
+caught by @code{with-continuation-barrier}.  In that case, a short
+message is printed to the current error port and @code{#f} is returned.
+
+Thus, @code{with-continuation-barrier} returns exactly once.
+@end deffn
+
+@deftypefn {C Function} {void *} scm_c_with_continuation_barrier (void *(*func) (void *), void *data)
+Like @code{scm_with_continuation_barrier} but call @var{func} on
+@var{data}.  When an error is caught, @code{NULL} is returned.
+@end deftypefn
+
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End: