This SRFI provides parameter objects, which implement dynamically bound locations for values. The functions below are available from
(use-modules (srfi srfi-39))
A parameter object is a procedure. Called with no arguments it returns its value, called with one argument it sets the value.
(define my-param (make-parameter 123)) (my-param) ⇒ 123 (my-param 456) (my-param) ⇒ 456
parameterize special form establishes new locations for
parameters, those new locations having effect within the dynamic scope
parameterize body. Leaving restores the previous
locations, or re-entering through a saved continuation will again use
the new locations.
(parameterize ((my-param 789)) (my-param) ⇒ 789 ) (my-param) ⇒ 456
Parameters are like dynamically bound variables in other Lisp dialets. They allow an application to establish parameter settings (as the name suggests) just for the execution of a particular bit of code, restoring when done. Examples of such parameters might be case-sensitivity for a search, or a prompt for user input.
Global variables are not as good as parameter objects for this sort of
thing. Changes to them are visible to all threads, but in Guile
parameter object locations are per-thread, thereby truely limiting the
parameterize to just its dynamic execution.
Passing arguments to functions is thread-safe, but that soon becomes tedious when there's more than a few or when they need to pass down through several layers of calls before reaching the point they should affect. And introducing a new setting to existing code is often easier with a parameter object than adding arguments.
Return a new parameter object, with initial value init.
A parameter object is a procedure. When called
(param)it returns its value, or a call
(param val)sets its value. For example,(define my-param (make-parameter 123)) (my-param) ⇒ 123 (my-param 456) (my-param) ⇒ 456
If a converter is given, then a call
val)is made for each value set, its return is the value stored. Such a call is made for the init initial value too.
A converter allows values to be validated, or put into a canonical form. For example,(define my-param (make-parameter 123 (lambda (val) (if (not (number? val)) (error "must be a number")) (inexact->exact val)))) (my-param 0.75) (my-param) ⇒ 3/4
Establish a new dynamic scope with the given params bound to new locations and set to the given values. body is evaluated in that environment, the result is the return from the last form in body.
Each param is an expression which is evaluated to get the parameter object. Often this will just be the name of a variable holding the object, but it can be anything that evaluates to a parameter.
The param expressions and value expressions are all evaluated before establishing the new dynamic bindings, and they're evaluated in an unspecified order.
For example,(define prompt (make-parameter "Type something: ")) (define (get-input) (display (prompt)) ...) (parameterize ((prompt "Type a number: ")) (get-input) ...)
This SRFI extends the core
current-output-port, making them parameter objects. The Guile-specific
current-error-portis extended too, for consistency. (see Default Ports.)
This is an upwardly compatible extension, a plain call like
(current-input-port)still returns the current input port, and
set-current-input-portcan still be used. But the port can now also be set with
(current-input-port my-port)and bound dynamically with
Establish a new dynamic scope, as per
parameterizeabove, taking parameters from param-list and corresponding values from values-list. A call
)is made in the new scope and the result from that thunk is the return from
This function is a Guile-specific addition to the SRFI, it's similar to the core
with-fluids*(see Fluids and Dynamic States).
Parameter objects are implemented using fluids (see Fluids and Dynamic States), so each dynamic state has it's own parameter locations. That includes the separate locations when outside any
parameterizeform. When a parameter is created it gets a separate initial location in each dynamic state, all initialized to the given init value.
As alluded to above, because each thread usually has a separate dynamic state, each thread has it's own locations behind parameter objects, and changes in one thread are not visible to any other. When a new dynamic state or thread is created, the values of parameters in the originating context are copied, into new locations.
SRFI-39 doesn't specify the interaction between parameter objects and threads, so the threading behaviour described here should be regarded as Guile-specific.