* Makefile.am: Fix ETAGS_ARGS to recognize GUILE_PROC,

[bpt/guile.git] / libguile / root.c

diff --git a/libguile/root.c b/libguile/root.c
index 5d2dd8d..0239901 100644 (file)
--- a/libguile/root.c
+++ b/libguile/root.c
@@ -337,7 +337,48 @@ cwdr (SCM proc, SCM a1, SCM args, SCM handler, SCM_STACKITEM *stack_start)
 
 GUILE_PROC(scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0,
            (SCM thunk, SCM handler),
-"")
+"Evaluate @var{(thunk)} in a new dynamic context, returning its value.
+
+If an error occurs during evaluation, apply @var{handler} to the
+arguments to the throw, just as @code{throw} would.  If this happens,
+@var{handler} is called outside the scope of the new root -- it is
+called in the same dynamic context in which
+@code{call-with-dynamic-root} was evaluated.
+
+If @var{thunk} captures a continuation, the continuation is rooted at
+the call to @var{thunk}.  In particular, the call to
+@code{call-with-dynamic-root} is not captured.  Therefore,
+@code{call-with-dynamic-root} always returns at most one time.
+
+Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
+the root and a new chain started for @var{thunk}.  Therefore, this call
+may not do what you expect:
+
+@example
+;; Almost certainly a bug:
+(with-output-to-port
+ some-port
+
+ (lambda ()
+   (call-with-dynamic-root
+    (lambda ()
+      (display 'fnord)
+      (newline))
+    (lambda (errcode) errcode))))
+@end example
+
+The problem is, on what port will @samp{fnord\n} be displayed?  You
+might expect that because of the @code{with-output-to-port} that
+it will be displayed on the port bound to @code{some-port}.  But it
+probably won't -- before evaluating the thunk, dynamic winds are
+unwound, including those created by @code{with-output-to-port}.
+So, the standard output port will have been re-set to its default value
+before @code{display} is evaluated.
+
+(This function was added to Guile mostly to help calls to functions in C
+libraries that can not tolerate non-local exits or calls that return
+multiple times.  If such functions call back to the interpreter, it should
+be under a new dynamic root.)")
 #define FUNC_NAME s_scm_call_with_dynamic_root
 {
   SCM_STACKITEM stack_place;
@@ -347,7 +388,11 @@ GUILE_PROC(scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0,
 
 GUILE_PROC(scm_dynamic_root, "dynamic-root", 0, 0, 0, 
            (),
-"")
+"Return an object representing the current dynamic root.
+
+These objects are only useful for comparison using @code{eq?}.
+They are currently represented as numbers, but your code should
+in no way depend on this.")
 #define FUNC_NAME s_scm_dynamic_root
 {
   return scm_ulong2num (SCM_SEQ (scm_root->rootcont));