mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-01 12:20:26 +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 @cindex fluids
A @emph{fluid} is an object that can store one value per @emph{dynamic A @emph{fluid} is a variable whose value is associated with the dynamic
state}. Each thread has a current dynamic state, and when accessing a extent of a function call. In the same way that an operating system
fluid, this current dynamic state is used to provide the actual value. runs a process with a given set of current input and output ports (or
In this way, fluids can be used for thread local storage. Additionally, file descriptors), in Guile you can arrange to call a function while
the set of current fluid values can be captured by a dynamic state and binding a fluid to a particular value. That association between fluid
reinstated in some other dynamic extent, possibly in another thread and value will exist during the dynamic extent of the function call.
even.
Fluids are a building block for implementing dynamically scoped Fluids are a therefore a building block for implementing dynamically
variables. Dynamically scoped variables are useful when you want to set scoped variables. Dynamically scoped variables are useful when you want
a variable to a value during some dynamic extent in the execution of to set a variable to a value during some dynamic extent in the execution
your program and have them revert to their original value when the 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 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 Guile uses fluids to implement parameters (@pxref{Parameters}). Usually
you just want to use parameters directly. However it can be useful to 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 know what a fluid is and how it works, so that's what this section is
about. 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 New fluids are created with @code{make-fluid} and @code{fluid?} is
used for testing whether an object is actually a fluid. The values used for testing whether an object is actually a fluid. The values
stored in a fluid can be accessed with @code{fluid-ref} and 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 @deffn {Scheme Procedure} set-current-dynamic-state state
@deffnx {C Function} scm_set_current_dynamic_state (state) @deffnx {C Function} scm_set_current_dynamic_state (state)
Set the current dynamic state object to @var{state} Restore the saved fluid-value associations from @var{state}, replacing
and return the previous current dynamic state object. the current fluid-value associations. Return the current fluid-value
associatoins as a dynamic state object, as in
@code{current-dynamic-state}.
@end deffn @end deffn
@deffn {Scheme Procedure} with-dynamic-state state proc @deffn {Scheme Procedure} with-dynamic-state state proc
@deffnx {C Function} scm_with_dynamic_state (state, proc) @deffnx {C Function} scm_with_dynamic_state (state, proc)
Call @var{proc} while @var{state} is the current dynamic Call @var{proc} while the fluid bindings from @var{state} have been made
state object. 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 @end deffn
@deftypefn {C Procedure} void scm_dynwind_current_dynamic_state (SCM state) @deftypefn {C Procedure} void scm_dynwind_current_dynamic_state (SCM state)
Set the current dynamic state to @var{state} for the current dynwind 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 @end deftypefn
@deftypefn {C Procedure} {void *} scm_c_with_dynamic_state (SCM state, void *(*func)(void *), void *data) @deftypefn {C Procedure} {void *} scm_c_with_dynamic_state (SCM state, void *(*func)(void *), void *data)