mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 03:40:34 +02:00
Code Activity

Update fluids / dynstate docs

Browse source 
* doc/ref/api-control.texi (Fluids and Dynamic States): Update
  documentation.
This commit is contained in:
Andy Wingo 2016-12-06 21:31:30 +01:00
parent 500e4a83e4
commit 842ba2fe33
1 changed files with 34 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

51
doc/ref/api-control.texi
View file

@ -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.
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 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
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)