Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.

6.21.7 Fluids and Dynamic States

A fluid is an object that can store one value per 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, but they are in fact more flexible: dynamic states are objects of their own and can be made current for more than one thread at the same time, or only be made current temporarily, for example.

Fluids can also be used to simulate the desirable effects of 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 with-fluids below for details.

New fluids are created with make-fluid and fluid? is used for testing whether an object is actually a fluid. The values stored in a fluid can be accessed with fluid-ref and fluid-set!.

Scheme Procedure: make-fluid [dflt]

C Function: scm_make_fluid ()

C Function: scm_make_fluid_with_default (dflt)

Return a newly created fluid, whose initial value is dflt, or #f if dflt is not given. Fluids are objects that can hold one value per dynamic state. That is, modifications to this value are only visible to code that executes with the same dynamic state as the modifying code. When a new dynamic state is constructed, it inherits the values from its parent. Because each thread normally executes with its own dynamic state, you can use fluids for thread local storage.

Scheme Procedure: make-unbound-fluid

C Function: scm_make_unbound_fluid ()

Return a new fluid that is initially unbound (instead of being implicitly bound to some definite value).

Scheme Procedure: fluid? obj

C Function: scm_fluid_p (obj)

Return #t if obj is a fluid; otherwise, return #f.

Scheme Procedure: fluid-ref fluid

C Function: scm_fluid_ref (fluid)

Return the value associated with fluid in the current dynamic root. If fluid has not been set, then return its default value. Calling fluid-ref on an unbound fluid produces a runtime error.

Scheme Procedure: fluid-set! fluid value

C Function: scm_fluid_set_x (fluid, value)

Set the value associated with fluid in the current dynamic root.

Scheme Procedure: fluid-unset! fluid

C Function: scm_fluid_unset_x (fluid)

Disassociate the given fluid from any value, making it unbound.

Scheme Procedure: fluid-bound? fluid

C Function: scm_fluid_bound_p (fluid)

Returns #t if the given fluid is bound to a value, otherwise #f.

with-fluids* temporarily changes the values of one or more fluids, so that the given procedure and each procedure called by it access the given values. After the procedure returns, the old values are restored.

Scheme Procedure: with-fluid* fluid value thunk

C Function: scm_with_fluid (fluid, value, thunk)

Set fluid to value temporarily, and call thunk. thunk must be a procedure with no argument.

Scheme Procedure: with-fluids* fluids values thunk

C Function: scm_with_fluids (fluids, values, thunk)

Set fluids to values temporary, and call thunk. fluids must be a list of fluids and values must be the same number of their values to be applied. Each substitution is done in the order given. thunk must be a procedure with no argument. It is called inside a dynamic-wind and the fluids are set/restored when control enter or leaves the established dynamic extent.

Scheme Macro: with-fluids ((fluid value) …) body1 body2 …

Execute body body1 body2 … while each fluid is set to the corresponding value. Both fluid and value are evaluated and fluid must yield a fluid. The body is executed inside a dynamic-wind and the fluids are set/restored when control enter or leaves the established dynamic extent.

C Function: SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)

C Function: SCM scm_c_with_fluid (SCM fluid, SCM val, SCM (*cproc)(void *), void *data)

The function scm_c_with_fluids is like scm_with_fluids except that it takes a C function to call instead of a Scheme thunk.

The function scm_c_with_fluid is similar but only allows one fluid to be set instead of a list.

C Function: void scm_dynwind_fluid (SCM fluid, SCM val)

This function must be used inside a pair of calls to scm_dynwind_begin and scm_dynwind_end (see Dynamic Wind). During the dynwind context, the fluid fluid is set to val.

More precisely, the value of the fluid is swapped with a ‘backup’ value whenever the dynwind context is entered or left. The backup value is initialized with the val argument.

Scheme Procedure: make-dynamic-state [parent]

C Function: scm_make_dynamic_state (parent)

Return a copy of the dynamic state object parent or of the current dynamic state when parent is omitted.

Scheme Procedure: dynamic-state? obj

C Function: scm_dynamic_state_p (obj)

Return #t if obj is a dynamic state object; return #f otherwise.

C Procedure: int scm_is_dynamic_state (SCM obj)

Return non-zero if obj is a dynamic state object; return zero otherwise.

Scheme Procedure: current-dynamic-state

C Function: scm_current_dynamic_state ()

Return the current dynamic state object.

Scheme Procedure: set-current-dynamic-state state

C Function: scm_set_current_dynamic_state (state)

Set the current dynamic state object to state and return the previous current dynamic state object.

Scheme Procedure: with-dynamic-state state proc

C Function: scm_with_dynamic_state (state, proc)

Call proc while state is the current dynamic state object.

C Procedure: void scm_dynwind_current_dynamic_state (SCM state)

Set the current dynamic state to state for the current dynwind context.

C Procedure: void * scm_c_with_dynamic_state (SCM state, void *(*func)(void *), void *data)

Like scm_with_dynamic_state, but call func with data.