www.delorie.com/gnu/docs/guile/guile_372.html

search

	Buy GNU books!

Guile Reference Manual

32.5 Fluids

Fluids are objects to store values in. They have a few properties which make them useful in certain situations: Fluids can have one value per dynamic root (see section 32.3 Dynamic Roots), so that changes to the value in a fluid are only visible in the same dynamic root. Since threads are executed in separate dynamic roots, fluids can be used for thread local storage (see section 32.4 Threads).

Fluids can be used to simulate dynamically scoped variables. These are used in several (especially in older) dialects of lisp, such as in Emacs Lisp, and they work a bit like global variables in that they can be modified by the caller of a procedure, and the called procedure will see the changes. With lexically scoped variables--which are normally used in Scheme--this cannot happen. 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.

Scheme Procedure: make-fluid

C Function: scm_make_fluid ()

Return a newly created fluid. Fluids are objects of a certain type (a smob) that can hold one SCM value per dynamic root. That is, modifications to this value are only visible to code that executes within the same dynamic root as the modifying code. When a new dynamic root is constructed, it inherits the values from its parent. Because each thread executes in its own dynamic root, you can use fluids for thread local storage.

Scheme Procedure: fluid? obj

C Function: scm_fluid_p (obj)

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

The values stored in a fluid can be accessed with fluid-ref and fluid-set!.

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 #f.

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.

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-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 one after another. thunk must be a procedure with no argument.