summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/api-control.texi53
1 files changed, 35 insertions, 18 deletions
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 8b20e3e45..4fe753774 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
-@code{with-fluids} below for details.
+@code{with-fluids} 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
+@emph{dynamic 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
+@code{current-dynamic-state}.
@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
+@var{proc}, 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)