[Guile-commits] 02/04: Update fluids / dynstate docs

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit 842ba2fe3329e19f28d0770cec2ff3616b1fa1da
Author: Andy Wingo <address@hidden>
Date:   Tue Dec 6 21:31:30 2016 +0100

    Update fluids / dynstate docs
    
    * doc/ref/api-control.texi (Fluids and Dynamic States): Update
      documentation.
---
 doc/ref/api-control.texi |   53 ++++++++++++++++++++++++++++++----------------
 1 file changed, 35 insertions(+), 18 deletions(-)

diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 8b20e3e..4fe7537 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -1665,26 +1665,36 @@ context is exited, whether normally or non-locally.
 
 @cindex fluids
 
-A @emph{fluid} is an object that can store one value per @emph{dynamic
-state}.  Each thread has a current dynamic state, and when accessing a
-fluid, this current dynamic state is used to provide the actual value.
-In this way, fluids can be used for thread local storage.  Additionally,
-the set of current fluid values can be captured by a dynamic state and
-reinstated in some other dynamic extent, possibly in another thread
-even.
-
-Fluids are a building block for implementing dynamically scoped
-variables.  Dynamically scoped variables are useful when you want to set
-a variable to a value during some dynamic extent in the execution of
-your program and have them revert to their original value when the
+A @emph{fluid} is a variable whose value is associated with the dynamic
+extent of a function call.  In the same way that an operating system
+runs a process with a given set of current input and output ports (or
+file descriptors), in Guile you can arrange to call a function while
+binding a fluid to a particular value.  That association between fluid
+and value will exist during the dynamic extent of the function call.
+
+Fluids are a therefore a building block for implementing dynamically
+scoped variables.  Dynamically scoped variables are useful when you want
+to set a variable to a value during some dynamic extent in the execution
+of your program and have them revert to their original value when the
 control flow is outside of this dynamic extent.  See the description of
address@hidden below for details.
address@hidden below for details.  This association between fluids,
+values, and dynamic extents is robust to multiple entries (as when a
+captured continuation is invoked more than once) and early exits (for
+example, when throwing exceptions).
 
 Guile uses fluids to implement parameters (@pxref{Parameters}).  Usually
 you just want to use parameters directly.  However it can be useful to
 know what a fluid is and how it works, so that's what this section is
 about.
 
+The current set of fluid-value associations can be captured in a
address@hidden state} object.  A dynamic extent is simply that: a
+snapshot of the current fluid-value associations.  Guile users can
+capture the current dynamic state with @code{current-dynamic-state} and
+restore it later via @code{with-dynamic-state} or similar procedures.
+This facility is especially useful when implementing lightweight
+thread-like abstractions.
+
 New fluids are created with @code{make-fluid} and @code{fluid?} is
 used for testing whether an object is actually a fluid.  The values
 stored in a fluid can be accessed with @code{fluid-ref} and
@@ -1807,19 +1817,26 @@ dynamic state object.
 
 @deffn {Scheme Procedure} set-current-dynamic-state state
 @deffnx {C Function} scm_set_current_dynamic_state (state)
-Set the current dynamic state object to @var{state}
-and return the previous current dynamic state object.
+Restore the saved fluid-value associations from @var{state}, replacing
+the current fluid-value associations.  Return the current fluid-value
+associatoins as a dynamic state object, as in
address@hidden
 @end deffn
 
 @deffn {Scheme Procedure} with-dynamic-state state proc
 @deffnx {C Function} scm_with_dynamic_state (state, proc)
-Call @var{proc} while @var{state} is the current dynamic
-state object.
+Call @var{proc} while the fluid bindings from @var{state} have been made
+current, saving the current fluid bindings.  When control leaves the
+invocation of @var{proc}, restore the saved bindings, saving instead the
+fluid bindings from inside the call.  If control later re-enters
address@hidden, restore those saved bindings, saving the current bindings,
+and so on.
 @end deffn
 
 @deftypefn {C Procedure} void scm_dynwind_current_dynamic_state (SCM state)
 Set the current dynamic state to @var{state} for the current dynwind
-context.
+context.  Like @code{with-dynamic-state}, but in terms of Guile's
+``dynwind'' C API.
 @end deftypefn
 
 @deftypefn {C Procedure} {void *} scm_c_with_dynamic_state (SCM state, void 
*(*func)(void *), void *data)