@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, 2010, 2012, 2013
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Scheduling
@section Threads, Mutexes, Asyncs and Dynamic Roots
* Blocking:: How to block properly in guile mode.
* Critical Sections:: Avoiding concurrency and reentries.
* Fluids and Dynamic States:: Thread-local variables, etc.
+* Parameters:: Dynamic scoping in Scheme.
+* Futures:: Fine-grain parallelism.
* Parallel Forms:: Parallel execution of forms.
@end menu
This way, you can cause threads to asynchronously execute arbitrary
code.
-User asyncs offer a convenient means of queueing procedures for future
+User asyncs offer a convenient means of queuing procedures for future
execution and triggering this execution. They will not be executed
automatically.
@cindex Guile threads
@cindex POSIX threads
+Guile supports POSIX threads, unless it was configured with
+@code{--without-threads} or the host lacks POSIX thread support. When
+thread support is available, the @code{threads} feature is provided
+(@pxref{Feature Manipulation, @code{provided?}}).
+
+The procedures below manipulate Guile threads, which are wrappers around
+the system's POSIX threads. For application-level parallelism, using
+higher-level constructs, such as futures, is recommended
+(@pxref{Futures}).
+
@deffn {Scheme Procedure} all-threads
@deffnx {C Function} scm_all_threads ()
Return a list of all threads.
@deffn {Scheme Procedure} thread? obj
@deffnx {C Function} scm_thread_p (obj)
-Return @code{#t} iff @var{obj} is a thread; otherwise, return
+Return @code{#t} ff @var{obj} is a thread; otherwise, return
@code{#f}.
@end deffn
@deffn {Scheme Procedure} thread-exited? thread
@deffnx {C Function} scm_thread_exited_p (thread)
-Return @code{#t} iff @var{thread} has exited.
+Return @code{#t} if @var{thread} has exited, or @code{#f} otherwise.
@end deffn
@c begin (texi-doc-string "guile" "yield")
@code{(ice-9 threads)} module. These provide standardized
thread creation.
-@deffn macro make-thread proc [args@dots{}]
-Apply @var{proc} to @var{args} in a new thread formed by
+@deffn macro make-thread proc arg @dots{}
+Apply @var{proc} to @var{arg} @dots{} in a new thread formed by
@code{call-with-new-thread} using a default error handler that display
-the error to the current error port. The @var{args@dots{}}
+the error to the current error port. The @var{arg} @dots{}
expressions are evaluated in the new thread.
@end deffn
-@deffn macro begin-thread first [rest@dots{}]
-Evaluate forms @var{first} and @var{rest} in a new thread formed by
+@deffn macro begin-thread expr1 expr2 @dots{}
+Evaluate forms @var{expr1} @var{expr2} @dots{} in a new thread formed by
@code{call-with-new-thread} using a default error handler that display
the error to the current error port.
@end deffn
in all threads is one way to avoid such problems.
@sp 1
-@deffn {Scheme Procedure} make-mutex . flags
+@deffn {Scheme Procedure} make-mutex flag @dots{}
@deffnx {C Function} scm_make_mutex ()
@deffnx {C Function} scm_make_mutex_with_flags (SCM flags)
-Return a new mutex. It is initially unlocked. If @var{flags} is
+Return a new mutex. It is initially unlocked. If @var{flag} @dots{} is
specified, it must be a list of symbols specifying configuration flags
for the newly-created mutex. The supported flags are:
@table @code
@deffn {Scheme Procedure} mutex? obj
@deffnx {C Function} scm_mutex_p (obj)
-Return @code{#t} iff @var{obj} is a mutex; otherwise, return
+Return @code{#t} if @var{obj} is a mutex; otherwise, return
@code{#f}.
@end deffn
@code{wait-condition-variable}, except that the mutex is left in an
unlocked state when the function returns.)
-When @var{timeout} is also given, it specifies a point in time where
-the waiting should be aborted. It can be either an integer as
-returned by @code{current-time} or a pair as returned by
+When @var{timeout} is also given and not false, it specifies a point in
+time where the waiting should be aborted. It can be either an integer
+as returned by @code{current-time} or a pair as returned by
@code{gettimeofday}. When the waiting is aborted, @code{#f} is
returned. Otherwise the function returns @code{#t}.
@end deffn
@deffn {Scheme Procedure} condition-variable? obj
@deffnx {C Function} scm_condition_variable_p (obj)
-Return @code{#t} iff @var{obj} is a condition variable; otherwise,
+Return @code{#t} if @var{obj} is a condition variable; otherwise,
return @code{#f}.
@end deffn
(use-modules (ice-9 threads))
@end example
-@deffn macro with-mutex mutex [body@dots{}]
-Lock @var{mutex}, evaluate the @var{body} forms, then unlock
-@var{mutex}. The return value is the return from the last @var{body}
-form.
+@deffn macro with-mutex mutex body1 body2 @dots{}
+Lock @var{mutex}, evaluate the body @var{body1} @var{body2} @dots{},
+then unlock @var{mutex}. The return value is that returned by the last
+body form.
The lock, body and unlock form the branches of a @code{dynamic-wind}
(@pxref{Dynamic Wind}), so @var{mutex} is automatically unlocked if an
-error or new continuation exits @var{body}, and is re-locked if
-@var{body} is re-entered by a captured continuation.
+error or new continuation exits the body, and is re-locked if
+the body is re-entered by a captured continuation.
@end deffn
-@deffn macro monitor body@dots{}
-Evaluate the @var{body} forms, with a mutex locked so only one thread
-can execute that code at any one time. The return value is the return
-from the last @var{body} form.
+@deffn macro monitor body1 body2 @dots{}
+Evaluate the body form @var{body1} @var{body2} @dots{} with a mutex
+locked so only one thread can execute that code at any one time. The
+return value is the return from the last body form.
Each @code{monitor} form has its own private mutex and the locking and
evaluation is as per @code{with-mutex} above. A standard mutex
-(@code{make-mutex}) is used, which means @var{body} must not
+(@code{make-mutex}) is used, which means the body must not
recursively re-enter the @code{monitor} form.
The term ``monitor'' comes from operating system theory, where it
@node Blocking
@subsection Blocking in Guile Mode
-A thread must not block outside of a libguile function while it is in
-guile mode. The following functions can be used to temporily leave
-guile mode or to perform some common blocking operations in a supported
-way.
+Up to Guile version 1.8, a thread blocked in guile mode would prevent
+the garbage collector from running. Thus threads had to explicitly
+leave guile mode with @code{scm_without_guile ()} before making a
+potentially blocking call such as a mutex lock, a @code{select ()}
+system call, etc. The following functions could be used to temporarily
+leave guile mode or to perform some common blocking operations in a
+supported way.
+
+Starting from Guile 2.0, blocked threads no longer hinder garbage
+collection. Thus, the functions below are not needed anymore. They can
+still be used to inform the GC that a thread is about to block, giving
+it a (small) optimization opportunity for ``stop the world'' garbage
+collections, should they occur while the thread is blocked.
@deftypefn {C Function} {void *} scm_without_guile (void *(*func) (void *), void *data)
Leave guile mode, call @var{func} on @var{data}, enter guile mode and
stored in a fluid can be accessed with @code{fluid-ref} and
@code{fluid-set!}.
-@deffn {Scheme Procedure} make-fluid
+@deffn {Scheme Procedure} make-fluid [dflt]
@deffnx {C Function} scm_make_fluid ()
-Return a newly created fluid.
+@deffnx {C Function} scm_make_fluid_with_default (dflt)
+Return a newly created fluid, whose initial value is @var{dflt}, or
+@code{#f} if @var{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
with its own dynamic state, you can use fluids for thread local storage.
@end deffn
+@deffn {Scheme Procedure} make-unbound-fluid
+@deffnx {C Function} scm_make_unbound_fluid ()
+Return a new fluid that is initially unbound (instead of being
+implicitly bound to some definite value).
+@end deffn
+
@deffn {Scheme Procedure} fluid? obj
@deffnx {C Function} scm_fluid_p (obj)
-Return @code{#t} iff @var{obj} is a fluid; otherwise, return
+Return @code{#t} if @var{obj} is a fluid; otherwise, return
@code{#f}.
@end deffn
@deffnx {C Function} scm_fluid_ref (fluid)
Return the value associated with @var{fluid} in the current
dynamic root. If @var{fluid} has not been set, then return
-@code{#f}.
+its default value. Calling @code{fluid-ref} on an unbound fluid produces
+a runtime error.
@end deffn
@deffn {Scheme Procedure} fluid-set! fluid value
Set the value associated with @var{fluid} in the current dynamic root.
@end deffn
+@deffn {Scheme Procedure} fluid-unset! fluid
+@deffnx {C Function} scm_fluid_unset_x (fluid)
+Disassociate the given fluid from any value, making it unbound.
+@end deffn
+
+@deffn {Scheme Procedure} fluid-bound? fluid
+@deffnx {C Function} scm_fluid_bound_p (fluid)
+Returns @code{#t} if the given fluid is bound to a value, otherwise
+@code{#f}.
+@end deffn
+
@code{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.
@var{fluids} must be a list of fluids and @var{values} must be the
same number of their values to be applied. Each substitution is done
in the order given. @var{thunk} must be a procedure with no argument.
-it is called inside a @code{dynamic-wind} and the fluids are
+It is called inside a @code{dynamic-wind} and the fluids are
set/restored when control enter or leaves the established dynamic
extent.
@end deffn
-@deffn {Scheme Macro} with-fluids ((fluid value) ...) body...
-Execute @var{body...} while each @var{fluid} is set to the
-corresponding @var{value}. Both @var{fluid} and @var{value} are
-evaluated and @var{fluid} must yield a fluid. @var{body...} is
-executed inside a @code{dynamic-wind} and the fluids are set/restored
-when control enter or leaves the established dynamic extent.
+@deffn {Scheme Macro} with-fluids ((fluid value) @dots{}) body1 body2 @dots{}
+Execute body @var{body1} @var{body2} @dots{} while each @var{fluid} is
+set to the corresponding @var{value}. Both @var{fluid} and @var{value}
+are evaluated and @var{fluid} must yield a fluid. The body is executed
+inside a @code{dynamic-wind} and the fluids are set/restored when
+control enter or leaves the established dynamic extent.
@end deffn
@deftypefn {C Function} SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)
@var{data}.
@end deftypefn
-@c @node Futures
-@c @subsection Futures
-@c @cindex futures
+@node Parameters
+@subsection Parameters
+
+@cindex SRFI-39
+@cindex parameter object
+@tindex Parameter
+
+A parameter object is a procedure. Calling it with no arguments returns
+its value. Calling it with one argument sets the value.
+
+@example
+(define my-param (make-parameter 123))
+(my-param) @result{} 123
+(my-param 456)
+(my-param) @result{} 456
+@end example
+
+The @code{parameterize} special form establishes new locations for
+parameters, those new locations having effect within the dynamic scope
+of the @code{parameterize} body. Leaving restores the previous
+locations. Re-entering (through a saved continuation) will again use
+the new locations.
+
+@example
+(parameterize ((my-param 789))
+ (my-param)) @result{} 789
+(my-param) @result{} 456
+@end example
+
+Parameters are like dynamically bound variables in other Lisp dialects.
+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 truly limiting the
+effect of @code{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.
+
+@deffn {Scheme Procedure} make-parameter init [converter]
+Return a new parameter object, with initial value @var{init}.
-@c -- Futures are disabled for the time being, see futures.h for an
-@c -- explanation.
+If a @var{converter} is given, then a call @code{(@var{converter}
+val)} is made for each value set, its return is the value stored.
+Such a call is made for the @var{init} initial value too.
-@c Futures are a convenient way to run a calculation in a new thread, and
-@c only wait for the result when it's actually needed.
+A @var{converter} allows values to be validated, or put into a
+canonical form. For example,
-@c Futures are similar to promises (@pxref{Delayed Evaluation}), in that
-@c they allow mainline code to continue immediately. But @code{delay}
-@c doesn't evaluate at all until forced, whereas @code{future} starts
-@c immediately in a new thread.
+@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) @result{} 3/4
+@end example
+@end deffn
+
+@deffn {library syntax} parameterize ((param value) @dots{}) body1 body2 @dots{}
+Establish a new dynamic scope with the given @var{param}s bound to new
+locations and set to the given @var{value}s. @var{body1} @var{body2}
+@dots{} is evaluated in that environment. The value returned is that of
+last body form.
+
+Each @var{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 @var{param} expressions and @var{value} expressions are all
+evaluated before establishing the new dynamic bindings, and they're
+evaluated in an unspecified order.
+
+For example,
+
+@example
+(define prompt (make-parameter "Type something: "))
+(define (get-input)
+ (display (prompt))
+ ...)
+
+(parameterize ((prompt "Type a number: "))
+ (get-input)
+ ...)
+@end example
+@end deffn
+
+Parameter objects are implemented using fluids (@pxref{Fluids and
+Dynamic States}), so each dynamic state has its own parameter
+locations. That includes the separate locations when outside any
+@code{parameterize} form. When a parameter is created it gets a
+separate initial location in each dynamic state, all initialized to the
+given @var{init} value.
+
+New code should probably just use parameters instead of fluids, because
+the interface is better. But for migrating old code or otherwise
+providing interoperability, Guile provides the @code{fluid->parameter}
+procedure:
+
+@deffn {Scheme Procedure} fluid->parameter fluid [conv]
+Make a parameter that wraps a fluid.
+
+The value of the parameter will be the same as the value of the fluid.
+If the parameter is rebound in some dynamic extent, perhaps via
+@code{parameterize}, the new value will be run through the optional
+@var{conv} procedure, as with any parameter. Note that unlike
+@code{make-parameter}, @var{conv} is not applied to the initial value.
+@end deffn
+
+As alluded to above, because each thread usually has a separate dynamic
+state, each thread has its 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.
+
+@cindex SRFI-39
+Guile's parameters conform to SRFI-39 (@pxref{SRFI-39}).
+
+
+@node Futures
+@subsection Futures
+@cindex futures
+@cindex fine-grain parallelism
+@cindex parallelism
+
+The @code{(ice-9 futures)} module provides @dfn{futures}, a construct
+for fine-grain parallelism. A future is a wrapper around an expression
+whose computation may occur in parallel with the code of the calling
+thread, and possibly in parallel with other futures. Like promises,
+futures are essentially proxies that can be queried to obtain the value
+of the enclosed expression:
+
+@lisp
+(touch (future (+ 2 3)))
+@result{} 5
+@end lisp
+
+However, unlike promises, the expression associated with a future may be
+evaluated on another CPU core, should one be available. This supports
+@dfn{fine-grain parallelism}, because even relatively small computations
+can be embedded in futures. Consider this sequential code:
+
+@lisp
+(define (find-prime lst1 lst2)
+ (or (find prime? lst1)
+ (find prime? lst2)))
+@end lisp
+
+The two arms of @code{or} are potentially computation-intensive. They
+are independent of one another, yet, they are evaluated sequentially
+when the first one returns @code{#f}. Using futures, one could rewrite
+it like this:
+
+@lisp
+(define (find-prime lst1 lst2)
+ (let ((f (future (find prime? lst2))))
+ (or (find prime? lst1)
+ (touch f))))
+@end lisp
+
+This preserves the semantics of @code{find-prime}. On a multi-core
+machine, though, the computation of @code{(find prime? lst2)} may be
+done in parallel with that of the other @code{find} call, which can
+reduce the execution time of @code{find-prime}.
+
+Futures may be nested: a future can itself spawn and then @code{touch}
+other futures, leading to a directed acyclic graph of futures. Using
+this facility, a parallel @code{map} procedure can be defined along
+these lines:
+
+@lisp
+(use-modules (ice-9 futures) (ice-9 match))
+
+(define (par-map proc lst)
+ (match lst
+ (()
+ '())
+ ((head tail ...)
+ (let ((tail (future (par-map proc tail)))
+ (head (proc head)))
+ (cons head (touch tail))))))
+@end lisp
+
+Note that futures are intended for the evaluation of purely functional
+expressions. Expressions that have side-effects or rely on I/O may
+require additional care, such as explicit synchronization
+(@pxref{Mutexes and Condition Variables}).
+
+Guile's futures are implemented on top of POSIX threads
+(@pxref{Threads}). Internally, a fixed-size pool of threads is used to
+evaluate futures, such that offloading the evaluation of an expression
+to another thread doesn't incur thread creation costs. By default, the
+pool contains one thread per available CPU core, minus one, to account
+for the main thread. The number of available CPU cores is determined
+using @code{current-processor-count} (@pxref{Processes}).
+
+When a thread touches a future that has not completed yet, it processes
+any pending future while waiting for it to complete, or just waits if
+there are no pending futures. When @code{touch} is called from within a
+future, the execution of the calling future is suspended, allowing its
+host thread to process other futures, and resumed when the touched
+future has completed. This suspend/resume is achieved by capturing the
+calling future's continuation, and later reinstating it (@pxref{Prompts,
+delimited continuations}).
+
+Note that @code{par-map} above is not tail-recursive. This could lead
+to stack overflows when @var{lst} is large compared to
+@code{(current-processor-count)}. To address that, @code{touch} uses
+the suspend mechanism described above to limit the number of nested
+futures executing on the same stack. Thus, the above code should never
+run into stack overflows.
+
+@deffn {Scheme Syntax} future exp
+Return a future for expression @var{exp}. This is equivalent to:
+
+@lisp
+(make-future (lambda () exp))
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} make-future thunk
+Return a future for @var{thunk}, a zero-argument procedure.
+
+This procedure returns immediately. Execution of @var{thunk} may begin
+in parallel with the calling thread's computations, if idle CPU cores
+are available, or it may start when @code{touch} is invoked on the
+returned future.
+
+If the execution of @var{thunk} throws an exception, that exception will
+be re-thrown when @code{touch} is invoked on the returned future.
+@end deffn
-@c @deffn {syntax} future expr
-@c Begin evaluating @var{expr} in a new thread, and return a ``future''
-@c object representing the calculation.
-@c @end deffn
+@deffn {Scheme Procedure} future? obj
+Return @code{#t} if @var{obj} is a future.
+@end deffn
-@c @deffn {Scheme Procedure} make-future thunk
-@c @deffnx {C Function} scm_make_future (thunk)
-@c Begin evaluating the call @code{(@var{thunk})} in a new thread, and
-@c return a ``future'' object representing the calculation.
-@c @end deffn
+@deffn {Scheme Procedure} touch f
+Return the result of the expression embedded in future @var{f}.
-@c @deffn {Scheme Procedure} future-ref f
-@c @deffnx {C Function} scm_future_ref (f)
-@c Return the value computed by the future @var{f}. If @var{f} has not
-@c yet finished executing then wait for it to do so.
-@c @end deffn
+If the result was already computed in parallel, @code{touch} returns
+instantaneously. Otherwise, it waits for the computation to complete,
+if it already started, or initiates it. In the former case, the calling
+thread may process other futures in the meantime.
+@end deffn
@node Parallel Forms
(use-modules (ice-9 threads))
@end example
-@deffn syntax parallel expr1 @dots{} exprN
+They provide high-level parallel constructs. The following functions
+are implemented in terms of futures (@pxref{Futures}). Thus they are
+relatively cheap as they re-use existing threads, and portable, since
+they automatically use one thread per available CPU core.
+
+@deffn syntax parallel expr @dots{}
Evaluate each @var{expr} expression in parallel, each in its own thread.
-Return the results as a set of @var{N} multiple values
-(@pxref{Multiple Values}).
+Return the results of @var{n} expressions as a set of @var{n} multiple
+values (@pxref{Multiple Values}).
@end deffn
-@deffn syntax letpar ((var1 expr1) @dots{} (varN exprN)) body@dots{}
+@deffn syntax letpar ((var expr) @dots{}) body1 body2 @dots{}
Evaluate each @var{expr} in parallel, each in its own thread, then bind
-the results to the corresponding @var{var} variables and evaluate
-@var{body}.
+the results to the corresponding @var{var} variables, and then evaluate
+@var{body1} @var{body2} @enddots{}
@code{letpar} is like @code{let} (@pxref{Local Bindings}), but all the
expressions for the bindings are evaluated in parallel.
@end deffn
-@deffn {Scheme Procedure} par-map proc lst1 @dots{} lstN
-@deffnx {Scheme Procedure} par-for-each proc lst1 @dots{} lstN
+@deffn {Scheme Procedure} par-map proc lst1 lst2 @dots{}
+@deffnx {Scheme Procedure} par-for-each proc lst1 lst2 @dots{}
Call @var{proc} on the elements of the given lists. @code{par-map}
returns a list comprising the return values from @var{proc}.
@code{par-for-each} returns an unspecified value, but waits for all
calls to complete.
-The @var{proc} calls are @code{(@var{proc} @var{elem1} @dots{}
-@var{elemN})}, where each @var{elem} is from the corresponding
-@var{lst}. Each @var{lst} must be the same length. The calls are
-made in parallel, each in its own thread.
+The @var{proc} calls are @code{(@var{proc} @var{elem1} @var{elem2}
+@dots{})}, where each @var{elem} is from the corresponding @var{lst} .
+Each @var{lst} must be the same length. The calls are potentially made
+in parallel, depending on the number of CPU cores available.
These functions are like @code{map} and @code{for-each} (@pxref{List
Mapping}), but make their @var{proc} calls in parallel.
@end deffn
-@deffn {Scheme Procedure} n-par-map n proc lst1 @dots{} lstN
-@deffnx {Scheme Procedure} n-par-for-each n proc lst1 @dots{} lstN
+Unlike those above, the functions described below take a number of
+threads as an argument. This makes them inherently non-portable since
+the specified number of threads may differ from the number of available
+CPU cores as returned by @code{current-processor-count}
+(@pxref{Processes}). In addition, these functions create the specified
+number of threads when they are called and terminate them upon
+completion, which makes them quite expensive.
+
+Therefore, they should be avoided.
+
+@deffn {Scheme Procedure} n-par-map n proc lst1 lst2 @dots{}
+@deffnx {Scheme Procedure} n-par-for-each n proc lst1 lst2 @dots{}
Call @var{proc} on the elements of the given lists, in the same way as
@code{par-map} and @code{par-for-each} above, but use no more than
@var{n} threads at any one time. The order in which calls are
keep the CPUs utilized, and not consume too much memory.
@end deffn
-@deffn {Scheme Procedure} n-for-each-par-map n sproc pproc lst1 @dots{} lstN
+@deffn {Scheme Procedure} n-for-each-par-map n sproc pproc lst1 lst2 @dots{}
Apply @var{pproc} to the elements of the given lists, and apply
@var{sproc} to each result returned by @var{pproc}. The final return
value is unspecified, but all calls will have been completed before
HCoop / bpt / guile.git / blobdiff