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