Adapt to new 'frame' names. Document scm_c_with_fluid,

scm_c_with_fluids, and scm_frame_fluid.

diff --git a/doc/ref/scheme-control.texi b/doc/ref/scheme-control.texi
index 023fdb9..d56b543 100644 (file)
--- a/doc/ref/scheme-control.texi
+++ b/doc/ref/scheme-control.texi
@@ -1050,12 +1050,12 @@ convenient construction of anonymous procedures that close over lexical
 variables, this will be, well, inconvenient.  Instead, C code can use
 @dfn{frames}.
 
-Guile offers the functions @code{scm_begin_frame} and
-@code{scm_end_frame} to delimit a dynamic extent.  Within this dynamic
+Guile offers the functions @code{scm_frame_begin} and
+@code{scm_frame_end} to delimit a dynamic extent.  Within this dynamic
 extent, which is called a @dfn{frame}, you can perform various
 @dfn{frame actions} that control what happens when the frame is entered
 or left.  For example, you can register a cleanup routine with
-@code{scm_on_unwind} that is executed when the frame is left.  There are
+@code{scm_frame_unwind} that is executed when the frame is left.  There are
 several other more specialized frame actions as well, for example to
 temporarily block the execution of asyncs or to temporarily change the
 current output port.  They are described elsewhere in this manual.
@@ -1100,19 +1100,19 @@ scm_foo (SCM s1, SCM s2)
 @{
   char *c_s1, *c_s2, *c_res;
 
-  scm_begin_frame (0);
+  scm_frame_begin (0);
 
   c_s1 = scm_to_string (s1);
-  scm_on_unwind (free, s1, SCM_F_EXPLICIT);
+  scm_frame_unwind (free, c_s1, SCM_F_EXPLICIT);
 
   c_s2 = scm_to_string (s2);
-  scm_on_unwind (free, s2, SCM_F_EXPLICIT);
+  scm_frame_unwind (free, c_s2, SCM_F_EXPLICIT);
 
   c_res = foo (c_s1, c_s2);
   if (c_res == NULL)
     scm_memory_error ("foo");
 
-  scm_end_frame ();
+  scm_frame_end ();
 
   return scm_take0str (res);
 @}
@@ -1131,7 +1131,7 @@ a frame can not be reentered non-locally.
 
 @end deftp
 
-@deftypefn {C Function} void scm_begin_frame (scm_t_frame_flags flags)
+@deftypefn {C Function} void scm_frame_begin (scm_t_frame_flags flags)
 The function @code{scm_begin_frame} starts a new frame and makes it the
 `current' one.  
 
@@ -1146,7 +1146,7 @@ is indeed ended properly.  If you fail to call @code{scm_end_frame} each
 @code{scm_begin_frame}, the behavior is undefined.
 @end deftypefn
 
-@deftypefn {C Function} void scm_end_frame ()
+@deftypefn {C Function} void scm_frame_end ()
 End the current frame explicitly and make the previous frame current.
 @end deftypefn
 
@@ -1162,25 +1162,25 @@ left locally.
 @end table
 @end deftp
 
-@deftypefn {C Function} void scm_on_unwind (void (*func)(void *), void *data, scm_t_wind_flags flags)
-@deftypefnx {C Function} void scm_on_unwind_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
+@deftypefn {C Function} void scm_frame_unwind (void (*func)(void *), void *data, scm_t_wind_flags flags)
+@deftypefnx {C Function} void scm_frame_unwind_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
 Arranges for @var{func} to be called with @var{data} as its arguments
 when the current frame ends implicitly.  If @var{flags} contains
 @code{SCM_F_WIND_EXPLICITLY}, @var{func} is also called when the frame
-ends explicitly with @code{scm_end_frame}.
+ends explicitly with @code{scm_frame_end}.
 
-The function @code{scm_on_unwind_with_scm} takes care that @var{data}
+The function @code{scm_frame_unwind_with_scm} takes care that @var{data}
 is protected from garbage collected.
 @end deftypefn
 
-@deftypefn {C Function} void scm_on_rewind (void (*func)(void *), void *data, scm_t_wind_flags flags)
-@deftypefnx {C Function} void scm_on_rewind_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
+@deftypefn {C Function} void scm_frame_rewind (void (*func)(void *), void *data, scm_t_wind_flags flags)
+@deftypefnx {C Function} void scm_frame_rewind_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
 Arrange for @var{func} to be called with @var{data} as its argument when
 the current frame is restarted by rewinding the stack.  When @var{flags}
 contains @code{SCM_F_WIND_EXPLICITLY}, @var{func} is called immediately
 as well.
 
-The function @code{scm_on_rewind_with_scm} takes care that @var{data}
+The function @code{scm_frame_rewind_with_scm} takes care that @var{data}
 is protected from garbage collected.
 @end deftypefn
 

diff --git a/doc/ref/scheme-io.texi b/doc/ref/scheme-io.texi
index 58deaf9..eb01ecb 100644 (file)
--- a/doc/ref/scheme-io.texi
+++ b/doc/ref/scheme-io.texi
@@ -634,17 +634,17 @@ Change the ports returned by @code{current-input-port},
 so that they use the supplied @var{port} for input or output.
 @end deffn
 
-@deftypefn {C Function} void scm_with_current_input_port (SCM port)
-@deftypefnx {C Function} void scm_with_current_output_port (SCM port)
-@deftypefnx {C Function} void scm_with_current_error_port (SCM port)
+@deftypefn {C Function} void scm_frame_current_input_port (SCM port)
+@deftypefnx {C Function} void scm_frame_current_output_port (SCM port)
+@deftypefnx {C Function} void scm_frame_current_error_port (SCM port)
 These functions must be used inside a pair of calls to
-@code{scm_begin_frame} and @code{scm_end_frame} (@pxref{Frames}).
+@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
 During the dynamic extent of the frame, the indicated port is set to
 @var{port}.
 
-More precisely, the the current port is saved when the dynamic extent is
-entered and set to @var{port}.  When the dynamic extent is left, the
-current port is stored in @var{port} and reset to the saved value.
+More precisely, the current port is swapped with a `backup' value
+whenever the frame is entered or left.  The backup value is
+initialized with the @var{port} argument.
 @end deftypefn
 
 @node Port Types

diff --git a/doc/ref/scheme-scheduling.texi b/doc/ref/scheme-scheduling.texi
index c9b4a02..e156d1b 100644 (file)
--- a/doc/ref/scheme-scheduling.texi
+++ b/doc/ref/scheme-scheduling.texi
@@ -147,15 +147,15 @@ returned by @var{proc}.  For the first two variants, call @var{proc}
 with no arguments; for the third, call it with @var{data}.
 @end deffn
 
-@deftypefn {C Function} void scm_with_blocked_asyncs ()
+@deftypefn {C Function} void scm_frame_block_asyncs ()
 This function must be used inside a pair of calls to
-@code{scm_begin_frame} and @code{scm_end_frame} (@pxref{Frames}).
+@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
 During the dynamic extent of the frame, asyncs are blocked by one level.
 @end deftypefn
 
-@deftypefn {C Function} void scm_with_unblocked_asyncs ()
+@deftypefn {C Function} void scm_frame_unblock_asyncs ()
 This function must be used inside a pair of calls to
-@code{scm_begin_frame} and @code{scm_end_frame} (@pxref{Frames}).
+@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
 During the dynamic extent of the frame, asyncs are unblocked by one
 level.
 @end deftypefn
@@ -631,8 +631,6 @@ You should call it in preference to the system @code{select}.
 
 @cindex fluids
 
-@c FIXME::martin: Review me!
-
 Fluids are objects to store values in.  They have a few properties
 which make them useful in certain situations: Fluids can have one
 value per dynamic root (@pxref{Dynamic Roots}), so that changes to the
@@ -704,6 +702,25 @@ executed inside a @code{dynamic-wind} and the fluids are set/restored
 when control enter or leaves the established dynamic extent.
 @end deffn
 
+@deftypefn {C Function} SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)
+@deftypefnx {C Function} SCM scm_c_with_fluid (SCM fluid, SCM val, SCM (*cproc)(void *), void *data)
+The function @code{scm_c_with_fluids} is like @code{scm_with_fluids}
+except that it takes a C function to call instead of a Scheme thunk.
+
+The function @code{scm_c_with_fluid} is similar but only allows one
+fluid to be set instead of a list.
+@end deftypefn
+
+@deftypefn {C Function} void scm_frame_fluid (SCM fluid, SCM val)
+This function must be used inside a pair of calls to
+@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
+During the dynamic extent of the frame, the fluid @var{fluid} is set
+to @var{val}.
+
+More precisely, the value of the fluid is swapped with a `backup'
+value whenever the frame is entered or left.  The backup value is
+initialized with the @var{val} argument.
+@end deftypefn
 
 @node Futures
 @section Futures