2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, 2010
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section Threads, Mutexes, Asyncs and Dynamic Roots
11 * Arbiters:: Synchronization primitives.
12 * Asyncs:: Asynchronous procedure invocation.
13 * Threads:: Multiple threads of execution.
14 * Mutexes and Condition Variables:: Synchronization primitives.
15 * Blocking:: How to block properly in guile mode.
16 * Critical Sections:: Avoiding concurrency and reentries.
17 * Fluids and Dynamic States:: Thread-local variables, etc.
18 * Futures:: Fine-grain parallelism.
19 * Parallel Forms:: Parallel execution of forms.
27 Arbiters are synchronization objects, they can be used by threads to
28 control access to a shared resource. An arbiter can be locked to
29 indicate a resource is in use, and unlocked when done.
31 An arbiter is like a light-weight mutex (@pxref{Mutexes and Condition
32 Variables}). It uses less memory and may be faster, but there's no
33 way for a thread to block waiting on an arbiter, it can only test and
34 get the status returned.
36 @deffn {Scheme Procedure} make-arbiter name
37 @deffnx {C Function} scm_make_arbiter (name)
38 Return an object of type arbiter and name @var{name}. Its
39 state is initially unlocked. Arbiters are a way to achieve
40 process synchronization.
43 @deffn {Scheme Procedure} try-arbiter arb
44 @deffnx {C Function} scm_try_arbiter (arb)
45 If @var{arb} is unlocked, then lock it and return @code{#t}.
46 If @var{arb} is already locked, then do nothing and return
50 @deffn {Scheme Procedure} release-arbiter arb
51 @deffnx {C Function} scm_release_arbiter (arb)
52 If @var{arb} is locked, then unlock it and return @code{#t}. If
53 @var{arb} is already unlocked, then do nothing and return @code{#f}.
55 Typical usage is for the thread which locked an arbiter to later
56 release it, but that's not required, any thread can release it.
67 Asyncs are a means of deferring the execution of Scheme code until it is
70 Guile provides two kinds of asyncs that share the basic concept but are
71 otherwise quite different: system asyncs and user asyncs. System asyncs
72 are integrated into the core of Guile and are executed automatically
73 when the system is in a state to allow the execution of Scheme code.
74 For example, it is not possible to execute Scheme code in a POSIX signal
75 handler, but such a signal handler can queue a system async to be
76 executed in the near future, when it is safe to do so.
78 System asyncs can also be queued for threads other than the current one.
79 This way, you can cause threads to asynchronously execute arbitrary
82 User asyncs offer a convenient means of queueing procedures for future
83 execution and triggering this execution. They will not be executed
92 @subsubsection System asyncs
94 To cause the future asynchronous execution of a procedure in a given
95 thread, use @code{system-async-mark}.
97 Automatic invocation of system asyncs can be temporarily disabled by
98 calling @code{call-with-blocked-asyncs}. This function works by
99 temporarily increasing the @emph{async blocking level} of the current
100 thread while a given procedure is running. The blocking level starts
101 out at zero, and whenever a safe point is reached, a blocking level
102 greater than zero will prevent the execution of queued asyncs.
104 Analogously, the procedure @code{call-with-unblocked-asyncs} will
105 temporarily decrease the blocking level of the current thread. You
106 can use it when you want to disable asyncs by default and only allow
109 In addition to the C versions of @code{call-with-blocked-asyncs} and
110 @code{call-with-unblocked-asyncs}, C code can use
111 @code{scm_dynwind_block_asyncs} and @code{scm_dynwind_unblock_asyncs}
112 inside a @dfn{dynamic context} (@pxref{Dynamic Wind}) to block or
113 unblock system asyncs temporarily.
115 @deffn {Scheme Procedure} system-async-mark proc [thread]
116 @deffnx {C Function} scm_system_async_mark (proc)
117 @deffnx {C Function} scm_system_async_mark_for_thread (proc, thread)
118 Mark @var{proc} (a procedure with zero arguments) for future execution
119 in @var{thread}. When @var{proc} has already been marked for
120 @var{thread} but has not been executed yet, this call has no effect.
121 When @var{thread} is omitted, the thread that called
122 @code{system-async-mark} is used.
124 This procedure is not safe to be called from signal handlers. Use
125 @code{scm_sigaction} or @code{scm_sigaction_for_thread} to install
129 @deffn {Scheme Procedure} call-with-blocked-asyncs proc
130 @deffnx {C Function} scm_call_with_blocked_asyncs (proc)
131 Call @var{proc} and block the execution of system asyncs by one level
132 for the current thread while it is running. Return the value returned
133 by @var{proc}. For the first two variants, call @var{proc} with no
134 arguments; for the third, call it with @var{data}.
137 @deftypefn {C Function} {void *} scm_c_call_with_blocked_asyncs (void * (*proc) (void *data), void *data)
138 The same but with a C function @var{proc} instead of a Scheme thunk.
141 @deffn {Scheme Procedure} call-with-unblocked-asyncs proc
142 @deffnx {C Function} scm_call_with_unblocked_asyncs (proc)
143 Call @var{proc} and unblock the execution of system asyncs by one
144 level for the current thread while it is running. Return the value
145 returned by @var{proc}. For the first two variants, call @var{proc}
146 with no arguments; for the third, call it with @var{data}.
149 @deftypefn {C Function} {void *} scm_c_call_with_unblocked_asyncs (void *(*proc) (void *data), void *data)
150 The same but with a C function @var{proc} instead of a Scheme thunk.
153 @deftypefn {C Function} void scm_dynwind_block_asyncs ()
154 During the current dynwind context, increase the blocking of asyncs by
155 one level. This function must be used inside a pair of calls to
156 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
160 @deftypefn {C Function} void scm_dynwind_unblock_asyncs ()
161 During the current dynwind context, decrease the blocking of asyncs by
162 one level. This function must be used inside a pair of calls to
163 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
168 @subsubsection User asyncs
170 A user async is a pair of a thunk (a parameterless procedure) and a
171 mark. Setting the mark on a user async will cause the thunk to be
172 executed when the user async is passed to @code{run-asyncs}. Setting
173 the mark more than once is satisfied by one execution of the thunk.
175 User asyncs are created with @code{async}. They are marked with
178 @deffn {Scheme Procedure} async thunk
179 @deffnx {C Function} scm_async (thunk)
180 Create a new user async for the procedure @var{thunk}.
183 @deffn {Scheme Procedure} async-mark a
184 @deffnx {C Function} scm_async_mark (a)
185 Mark the user async @var{a} for future execution.
188 @deffn {Scheme Procedure} run-asyncs list_of_a
189 @deffnx {C Function} scm_run_asyncs (list_of_a)
190 Execute all thunks from the marked asyncs of the list @var{list_of_a}.
196 @cindex Guile threads
197 @cindex POSIX threads
199 Guile supports POSIX threads, unless it was configured with
200 @code{--without-threads} or the host lacks POSIX thread support. When
201 thread support is available, the @code{threads} feature is provided
202 (@pxref{Feature Manipulation, @code{provided?}}).
204 The procedures below manipulate Guile threads, which are wrappers around
205 the system's POSIX threads. For application-level parallelism, using
206 higher-level constructs, such as futures, is recommended
209 @deffn {Scheme Procedure} all-threads
210 @deffnx {C Function} scm_all_threads ()
211 Return a list of all threads.
214 @deffn {Scheme Procedure} current-thread
215 @deffnx {C Function} scm_current_thread ()
216 Return the thread that called this function.
219 @c begin (texi-doc-string "guile" "call-with-new-thread")
220 @deffn {Scheme Procedure} call-with-new-thread thunk [handler]
221 Call @code{thunk} in a new thread and with a new dynamic state,
222 returning the new thread. The procedure @var{thunk} is called via
223 @code{with-continuation-barrier}.
225 When @var{handler} is specified, then @var{thunk} is called from
226 within a @code{catch} with tag @code{#t} that has @var{handler} as its
227 handler. This catch is established inside the continuation barrier.
229 Once @var{thunk} or @var{handler} returns, the return value is made
230 the @emph{exit value} of the thread and the thread is terminated.
233 @deftypefn {C Function} SCM scm_spawn_thread (scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data)
234 Call @var{body} in a new thread, passing it @var{body_data}, returning
235 the new thread. The function @var{body} is called via
236 @code{scm_c_with_continuation_barrier}.
238 When @var{handler} is non-@code{NULL}, @var{body} is called via
239 @code{scm_internal_catch} with tag @code{SCM_BOOL_T} that has
240 @var{handler} and @var{handler_data} as the handler and its data. This
241 catch is established inside the continuation barrier.
243 Once @var{body} or @var{handler} returns, the return value is made the
244 @emph{exit value} of the thread and the thread is terminated.
247 @deffn {Scheme Procedure} thread? obj
248 @deffnx {C Function} scm_thread_p (obj)
249 Return @code{#t} iff @var{obj} is a thread; otherwise, return
253 @c begin (texi-doc-string "guile" "join-thread")
254 @deffn {Scheme Procedure} join-thread thread [timeout [timeoutval]]
255 @deffnx {C Function} scm_join_thread (thread)
256 @deffnx {C Function} scm_join_thread_timed (thread, timeout, timeoutval)
257 Wait for @var{thread} to terminate and return its exit value. Threads
258 that have not been created with @code{call-with-new-thread} or
259 @code{scm_spawn_thread} have an exit value of @code{#f}. When
260 @var{timeout} is given, it specifies a point in time where the waiting
261 should be aborted. It can be either an integer as returned by
262 @code{current-time} or a pair as returned by @code{gettimeofday}.
263 When the waiting is aborted, @var{timeoutval} is returned (if it is
264 specified; @code{#f} is returned otherwise).
267 @deffn {Scheme Procedure} thread-exited? thread
268 @deffnx {C Function} scm_thread_exited_p (thread)
269 Return @code{#t} iff @var{thread} has exited.
272 @c begin (texi-doc-string "guile" "yield")
273 @deffn {Scheme Procedure} yield
274 If one or more threads are waiting to execute, calling yield forces an
275 immediate context switch to one of them. Otherwise, yield has no effect.
278 @deffn {Scheme Procedure} cancel-thread thread
279 @deffnx {C Function} scm_cancel_thread (thread)
280 Asynchronously notify @var{thread} to exit. Immediately after
281 receiving this notification, @var{thread} will call its cleanup handler
282 (if one has been set) and then terminate, aborting any evaluation that
285 Because Guile threads are isomorphic with POSIX threads, @var{thread}
286 will not receive its cancellation signal until it reaches a cancellation
287 point. See your operating system's POSIX threading documentation for
288 more information on cancellation points; note that in Guile, unlike
289 native POSIX threads, a thread can receive a cancellation notification
290 while attempting to lock a mutex.
293 @deffn {Scheme Procedure} set-thread-cleanup! thread proc
294 @deffnx {C Function} scm_set_thread_cleanup_x (thread, proc)
295 Set @var{proc} as the cleanup handler for the thread @var{thread}.
296 @var{proc}, which must be a thunk, will be called when @var{thread}
297 exits, either normally or by being canceled. Thread cleanup handlers
298 can be used to perform useful tasks like releasing resources, such as
299 locked mutexes, when thread exit cannot be predicted.
301 The return value of @var{proc} will be set as the @emph{exit value} of
304 To remove a cleanup handler, pass @code{#f} for @var{proc}.
307 @deffn {Scheme Procedure} thread-cleanup thread
308 @deffnx {C Function} scm_thread_cleanup (thread)
309 Return the cleanup handler currently installed for the thread
310 @var{thread}. If no cleanup handler is currently installed,
311 thread-cleanup returns @code{#f}.
314 Higher level thread procedures are available by loading the
315 @code{(ice-9 threads)} module. These provide standardized
318 @deffn macro make-thread proc [args@dots{}]
319 Apply @var{proc} to @var{args} in a new thread formed by
320 @code{call-with-new-thread} using a default error handler that display
321 the error to the current error port. The @var{args@dots{}}
322 expressions are evaluated in the new thread.
325 @deffn macro begin-thread first [rest@dots{}]
326 Evaluate forms @var{first} and @var{rest} in a new thread formed by
327 @code{call-with-new-thread} using a default error handler that display
328 the error to the current error port.
331 @node Mutexes and Condition Variables
332 @subsection Mutexes and Condition Variables
334 @cindex condition variable
336 A mutex is a thread synchronization object, it can be used by threads
337 to control access to a shared resource. A mutex can be locked to
338 indicate a resource is in use, and other threads can then block on the
339 mutex to wait for the resource (or can just test and do something else
340 if not available). ``Mutex'' is short for ``mutual exclusion''.
342 There are two types of mutexes in Guile, ``standard'' and
343 ``recursive''. They're created by @code{make-mutex} and
344 @code{make-recursive-mutex} respectively, the operation functions are
347 Note that for both types of mutex there's no protection against a
348 ``deadly embrace''. For instance if one thread has locked mutex A and
349 is waiting on mutex B, but another thread owns B and is waiting on A,
350 then an endless wait will occur (in the current implementation).
351 Acquiring requisite mutexes in a fixed order (like always A before B)
352 in all threads is one way to avoid such problems.
355 @deffn {Scheme Procedure} make-mutex . flags
356 @deffnx {C Function} scm_make_mutex ()
357 @deffnx {C Function} scm_make_mutex_with_flags (SCM flags)
358 Return a new mutex. It is initially unlocked. If @var{flags} is
359 specified, it must be a list of symbols specifying configuration flags
360 for the newly-created mutex. The supported flags are:
362 @item unchecked-unlock
363 Unless this flag is present, a call to `unlock-mutex' on the returned
364 mutex when it is already unlocked will cause an error to be signalled.
366 @item allow-external-unlock
367 Allow the returned mutex to be unlocked by the calling thread even if
368 it was originally locked by a different thread.
371 The returned mutex will be recursive.
376 @deffn {Scheme Procedure} mutex? obj
377 @deffnx {C Function} scm_mutex_p (obj)
378 Return @code{#t} iff @var{obj} is a mutex; otherwise, return
382 @deffn {Scheme Procedure} make-recursive-mutex
383 @deffnx {C Function} scm_make_recursive_mutex ()
384 Create a new recursive mutex. It is initially unlocked. Calling this
385 function is equivalent to calling `make-mutex' and specifying the
386 @code{recursive} flag.
389 @deffn {Scheme Procedure} lock-mutex mutex [timeout [owner]]
390 @deffnx {C Function} scm_lock_mutex (mutex)
391 @deffnx {C Function} scm_lock_mutex_timed (mutex, timeout, owner)
392 Lock @var{mutex}. If the mutex is already locked, then block and
393 return only when @var{mutex} has been acquired.
395 When @var{timeout} is given, it specifies a point in time where the
396 waiting should be aborted. It can be either an integer as returned
397 by @code{current-time} or a pair as returned by @code{gettimeofday}.
398 When the waiting is aborted, @code{#f} is returned.
400 When @var{owner} is given, it specifies an owner for @var{mutex} other
401 than the calling thread. @var{owner} may also be @code{#f},
402 indicating that the mutex should be locked but left unowned.
404 For standard mutexes (@code{make-mutex}), and error is signalled if
405 the thread has itself already locked @var{mutex}.
407 For a recursive mutex (@code{make-recursive-mutex}), if the thread has
408 itself already locked @var{mutex}, then a further @code{lock-mutex}
409 call increments the lock count. An additional @code{unlock-mutex}
410 will be required to finally release.
412 If @var{mutex} was locked by a thread that exited before unlocking it,
413 the next attempt to lock @var{mutex} will succeed, but
414 @code{abandoned-mutex-error} will be signalled.
416 When a system async (@pxref{System asyncs}) is activated for a thread
417 blocked in @code{lock-mutex}, the wait is interrupted and the async is
418 executed. When the async returns, the wait resumes.
421 @deftypefn {C Function} void scm_dynwind_lock_mutex (SCM mutex)
422 Arrange for @var{mutex} to be locked whenever the current dynwind
423 context is entered and to be unlocked when it is exited.
426 @deffn {Scheme Procedure} try-mutex mx
427 @deffnx {C Function} scm_try_mutex (mx)
428 Try to lock @var{mutex} as per @code{lock-mutex}. If @var{mutex} can
429 be acquired immediately then this is done and the return is @code{#t}.
430 If @var{mutex} is locked by some other thread then nothing is done and
431 the return is @code{#f}.
434 @deffn {Scheme Procedure} unlock-mutex mutex [condvar [timeout]]
435 @deffnx {C Function} scm_unlock_mutex (mutex)
436 @deffnx {C Function} scm_unlock_mutex_timed (mutex, condvar, timeout)
437 Unlock @var{mutex}. An error is signalled if @var{mutex} is not locked
438 and was not created with the @code{unchecked-unlock} flag set, or if
439 @var{mutex} is locked by a thread other than the calling thread and was
440 not created with the @code{allow-external-unlock} flag set.
442 If @var{condvar} is given, it specifies a condition variable upon
443 which the calling thread will wait to be signalled before returning.
444 (This behavior is very similar to that of
445 @code{wait-condition-variable}, except that the mutex is left in an
446 unlocked state when the function returns.)
448 When @var{timeout} is also given, it specifies a point in time where
449 the waiting should be aborted. It can be either an integer as
450 returned by @code{current-time} or a pair as returned by
451 @code{gettimeofday}. When the waiting is aborted, @code{#f} is
452 returned. Otherwise the function returns @code{#t}.
455 @deffn {Scheme Procedure} mutex-owner mutex
456 @deffnx {C Function} scm_mutex_owner (mutex)
457 Return the current owner of @var{mutex}, in the form of a thread or
458 @code{#f} (indicating no owner). Note that a mutex may be unowned but
462 @deffn {Scheme Procedure} mutex-level mutex
463 @deffnx {C Function} scm_mutex_level (mutex)
464 Return the current lock level of @var{mutex}. If @var{mutex} is
465 currently unlocked, this value will be 0; otherwise, it will be the
466 number of times @var{mutex} has been recursively locked by its current
470 @deffn {Scheme Procedure} mutex-locked? mutex
471 @deffnx {C Function} scm_mutex_locked_p (mutex)
472 Return @code{#t} if @var{mutex} is locked, regardless of ownership;
473 otherwise, return @code{#f}.
476 @deffn {Scheme Procedure} make-condition-variable
477 @deffnx {C Function} scm_make_condition_variable ()
478 Return a new condition variable.
481 @deffn {Scheme Procedure} condition-variable? obj
482 @deffnx {C Function} scm_condition_variable_p (obj)
483 Return @code{#t} iff @var{obj} is a condition variable; otherwise,
487 @deffn {Scheme Procedure} wait-condition-variable condvar mutex [time]
488 @deffnx {C Function} scm_wait_condition_variable (condvar, mutex, time)
489 Wait until @var{condvar} has been signalled. While waiting,
490 @var{mutex} is atomically unlocked (as with @code{unlock-mutex}) and
491 is locked again when this function returns. When @var{time} is given,
492 it specifies a point in time where the waiting should be aborted. It
493 can be either a integer as returned by @code{current-time} or a pair
494 as returned by @code{gettimeofday}. When the waiting is aborted,
495 @code{#f} is returned. When the condition variable has in fact been
496 signalled, @code{#t} is returned. The mutex is re-locked in any case
497 before @code{wait-condition-variable} returns.
499 When a system async is activated for a thread that is blocked in a
500 call to @code{wait-condition-variable}, the waiting is interrupted,
501 the mutex is locked, and the async is executed. When the async
502 returns, the mutex is unlocked again and the waiting is resumed. When
503 the thread block while re-acquiring the mutex, execution of asyncs is
507 @deffn {Scheme Procedure} signal-condition-variable condvar
508 @deffnx {C Function} scm_signal_condition_variable (condvar)
509 Wake up one thread that is waiting for @var{condvar}.
512 @deffn {Scheme Procedure} broadcast-condition-variable condvar
513 @deffnx {C Function} scm_broadcast_condition_variable (condvar)
514 Wake up all threads that are waiting for @var{condvar}.
518 The following are higher level operations on mutexes. These are
522 (use-modules (ice-9 threads))
525 @deffn macro with-mutex mutex [body@dots{}]
526 Lock @var{mutex}, evaluate the @var{body} forms, then unlock
527 @var{mutex}. The return value is the return from the last @var{body}
530 The lock, body and unlock form the branches of a @code{dynamic-wind}
531 (@pxref{Dynamic Wind}), so @var{mutex} is automatically unlocked if an
532 error or new continuation exits @var{body}, and is re-locked if
533 @var{body} is re-entered by a captured continuation.
536 @deffn macro monitor body@dots{}
537 Evaluate the @var{body} forms, with a mutex locked so only one thread
538 can execute that code at any one time. The return value is the return
539 from the last @var{body} form.
541 Each @code{monitor} form has its own private mutex and the locking and
542 evaluation is as per @code{with-mutex} above. A standard mutex
543 (@code{make-mutex}) is used, which means @var{body} must not
544 recursively re-enter the @code{monitor} form.
546 The term ``monitor'' comes from operating system theory, where it
547 means a particular bit of code managing access to some resource and
548 which only ever executes on behalf of one process at any one time.
553 @subsection Blocking in Guile Mode
555 Up to Guile version 1.8, a thread blocked in guile mode would prevent
556 the garbage collector from running. Thus threads had to explicitly
557 leave guile mode with @code{scm_without_guile ()} before making a
558 potentially blocking call such as a mutex lock, a @code{select ()}
559 system call, etc. The following functions could be used to temporarily
560 leave guile mode or to perform some common blocking operations in a
563 Starting from Guile 2.0, blocked threads no longer hinder garbage
564 collection. Thus, the functions below are not needed anymore. They can
565 still be used to inform the GC that a thread is about to block, giving
566 it a (small) optimization opportunity for ``stop the world'' garbage
567 collections, should they occur while the thread is blocked.
569 @deftypefn {C Function} {void *} scm_without_guile (void *(*func) (void *), void *data)
570 Leave guile mode, call @var{func} on @var{data}, enter guile mode and
571 return the result of calling @var{func}.
573 While a thread has left guile mode, it must not call any libguile
574 functions except @code{scm_with_guile} or @code{scm_without_guile} and
575 must not use any libguile macros. Also, local variables of type
576 @code{SCM} that are allocated while not in guile mode are not
577 protected from the garbage collector.
579 When used from non-guile mode, calling @code{scm_without_guile} is
580 still allowed: it simply calls @var{func}. In that way, you can leave
581 guile mode without having to know whether the current thread is in
585 @deftypefn {C Function} int scm_pthread_mutex_lock (pthread_mutex_t *mutex)
586 Like @code{pthread_mutex_lock}, but leaves guile mode while waiting for
590 @deftypefn {C Function} int scm_pthread_cond_wait (pthread_cond_t *cond, pthread_mutex_t *mutex)
591 @deftypefnx {C Function} int scm_pthread_cond_timedwait (pthread_cond_t *cond, pthread_mutex_t *mutex, struct timespec *abstime)
592 Like @code{pthread_cond_wait} and @code{pthread_cond_timedwait}, but
593 leaves guile mode while waiting for the condition variable.
596 @deftypefn {C Function} int scm_std_select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
597 Like @code{select} but leaves guile mode while waiting. Also, the
598 delivery of a system async causes this function to be interrupted with
599 error code @code{EINTR}.
602 @deftypefn {C Function} {unsigned int} scm_std_sleep ({unsigned int} seconds)
603 Like @code{sleep}, but leaves guile mode while sleeping. Also, the
604 delivery of a system async causes this function to be interrupted.
607 @deftypefn {C Function} {unsigned long} scm_std_usleep ({unsigned long} usecs)
608 Like @code{usleep}, but leaves guile mode while sleeping. Also, the
609 delivery of a system async causes this function to be interrupted.
613 @node Critical Sections
614 @subsection Critical Sections
616 @deffn {C Macro} SCM_CRITICAL_SECTION_START
617 @deffnx {C Macro} SCM_CRITICAL_SECTION_END
618 These two macros can be used to delimit a critical section.
619 Syntactically, they are both statements and need to be followed
620 immediately by a semicolon.
622 Executing @code{SCM_CRITICAL_SECTION_START} will lock a recursive
623 mutex and block the executing of system asyncs. Executing
624 @code{SCM_CRITICAL_SECTION_END} will unblock the execution of system
625 asyncs and unlock the mutex. Thus, the code that executes between
626 these two macros can only be executed in one thread at any one time
627 and no system asyncs will run. However, because the mutex is a
628 recursive one, the code might still be reentered by the same thread.
629 You must either allow for this or avoid it, both by careful coding.
631 On the other hand, critical sections delimited with these macros can
632 be nested since the mutex is recursive.
634 You must make sure that for each @code{SCM_CRITICAL_SECTION_START},
635 the corresponding @code{SCM_CRITICAL_SECTION_END} is always executed.
636 This means that no non-local exit (such as a signalled error) might
640 @deftypefn {C Function} void scm_dynwind_critical_section (SCM mutex)
641 Call @code{scm_dynwind_lock_mutex} on @var{mutex} and call
642 @code{scm_dynwind_block_asyncs}. When @var{mutex} is false, a recursive
643 mutex provided by Guile is used instead.
645 The effect of a call to @code{scm_dynwind_critical_section} is that
646 the current dynwind context (@pxref{Dynamic Wind}) turns into a
647 critical section. Because of the locked mutex, no second thread can
648 enter it concurrently and because of the blocked asyncs, no system
649 async can reenter it from the current thread.
651 When the current thread reenters the critical section anyway, the kind
652 of @var{mutex} determines what happens: When @var{mutex} is recursive,
653 the reentry is allowed. When it is a normal mutex, an error is
658 @node Fluids and Dynamic States
659 @subsection Fluids and Dynamic States
663 A @emph{fluid} is an object that can store one value per @emph{dynamic
664 state}. Each thread has a current dynamic state, and when accessing a
665 fluid, this current dynamic state is used to provide the actual value.
666 In this way, fluids can be used for thread local storage, but they are
667 in fact more flexible: dynamic states are objects of their own and can
668 be made current for more than one thread at the same time, or only be
669 made current temporarily, for example.
671 Fluids can also be used to simulate the desirable effects of
672 dynamically scoped variables. Dynamically scoped variables are useful
673 when you want to set a variable to a value during some dynamic extent
674 in the execution of your program and have them revert to their
675 original value when the control flow is outside of this dynamic
676 extent. See the description of @code{with-fluids} below for details.
678 New fluids are created with @code{make-fluid} and @code{fluid?} is
679 used for testing whether an object is actually a fluid. The values
680 stored in a fluid can be accessed with @code{fluid-ref} and
683 @deffn {Scheme Procedure} make-fluid
684 @deffnx {C Function} scm_make_fluid ()
685 Return a newly created fluid.
686 Fluids are objects that can hold one
687 value per dynamic state. That is, modifications to this value are
688 only visible to code that executes with the same dynamic state as
689 the modifying code. When a new dynamic state is constructed, it
690 inherits the values from its parent. Because each thread normally executes
691 with its own dynamic state, you can use fluids for thread local storage.
694 @deffn {Scheme Procedure} fluid? obj
695 @deffnx {C Function} scm_fluid_p (obj)
696 Return @code{#t} iff @var{obj} is a fluid; otherwise, return
700 @deffn {Scheme Procedure} fluid-ref fluid
701 @deffnx {C Function} scm_fluid_ref (fluid)
702 Return the value associated with @var{fluid} in the current
703 dynamic root. If @var{fluid} has not been set, then return
707 @deffn {Scheme Procedure} fluid-set! fluid value
708 @deffnx {C Function} scm_fluid_set_x (fluid, value)
709 Set the value associated with @var{fluid} in the current dynamic root.
712 @code{with-fluids*} temporarily changes the values of one or more fluids,
713 so that the given procedure and each procedure called by it access the
714 given values. After the procedure returns, the old values are restored.
716 @deffn {Scheme Procedure} with-fluid* fluid value thunk
717 @deffnx {C Function} scm_with_fluid (fluid, value, thunk)
718 Set @var{fluid} to @var{value} temporarily, and call @var{thunk}.
719 @var{thunk} must be a procedure with no argument.
722 @deffn {Scheme Procedure} with-fluids* fluids values thunk
723 @deffnx {C Function} scm_with_fluids (fluids, values, thunk)
724 Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
725 @var{fluids} must be a list of fluids and @var{values} must be the
726 same number of their values to be applied. Each substitution is done
727 in the order given. @var{thunk} must be a procedure with no argument.
728 it is called inside a @code{dynamic-wind} and the fluids are
729 set/restored when control enter or leaves the established dynamic
733 @deffn {Scheme Macro} with-fluids ((fluid value) ...) body...
734 Execute @var{body...} while each @var{fluid} is set to the
735 corresponding @var{value}. Both @var{fluid} and @var{value} are
736 evaluated and @var{fluid} must yield a fluid. @var{body...} is
737 executed inside a @code{dynamic-wind} and the fluids are set/restored
738 when control enter or leaves the established dynamic extent.
741 @deftypefn {C Function} SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)
742 @deftypefnx {C Function} SCM scm_c_with_fluid (SCM fluid, SCM val, SCM (*cproc)(void *), void *data)
743 The function @code{scm_c_with_fluids} is like @code{scm_with_fluids}
744 except that it takes a C function to call instead of a Scheme thunk.
746 The function @code{scm_c_with_fluid} is similar but only allows one
747 fluid to be set instead of a list.
750 @deftypefn {C Function} void scm_dynwind_fluid (SCM fluid, SCM val)
751 This function must be used inside a pair of calls to
752 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
753 Wind}). During the dynwind context, the fluid @var{fluid} is set to
756 More precisely, the value of the fluid is swapped with a `backup'
757 value whenever the dynwind context is entered or left. The backup
758 value is initialized with the @var{val} argument.
761 @deffn {Scheme Procedure} make-dynamic-state [parent]
762 @deffnx {C Function} scm_make_dynamic_state (parent)
763 Return a copy of the dynamic state object @var{parent}
764 or of the current dynamic state when @var{parent} is omitted.
767 @deffn {Scheme Procedure} dynamic-state? obj
768 @deffnx {C Function} scm_dynamic_state_p (obj)
769 Return @code{#t} if @var{obj} is a dynamic state object;
770 return @code{#f} otherwise.
773 @deftypefn {C Procedure} int scm_is_dynamic_state (SCM obj)
774 Return non-zero if @var{obj} is a dynamic state object;
775 return zero otherwise.
778 @deffn {Scheme Procedure} current-dynamic-state
779 @deffnx {C Function} scm_current_dynamic_state ()
780 Return the current dynamic state object.
783 @deffn {Scheme Procedure} set-current-dynamic-state state
784 @deffnx {C Function} scm_set_current_dynamic_state (state)
785 Set the current dynamic state object to @var{state}
786 and return the previous current dynamic state object.
789 @deffn {Scheme Procedure} with-dynamic-state state proc
790 @deffnx {C Function} scm_with_dynamic_state (state, proc)
791 Call @var{proc} while @var{state} is the current dynamic
795 @deftypefn {C Procedure} void scm_dynwind_current_dynamic_state (SCM state)
796 Set the current dynamic state to @var{state} for the current dynwind
800 @deftypefn {C Procedure} {void *} scm_c_with_dynamic_state (SCM state, void *(*func)(void *), void *data)
801 Like @code{scm_with_dynamic_state}, but call @var{func} with
808 @cindex fine-grain parallelism
811 The @code{(ice-9 futures)} module provides @dfn{futures}, a construct
812 for fine-grain parallelism. A future is a wrapper around an expression
813 whose computation may occur in parallel with the code of the calling
814 thread, and possibly in parallel with other futures. Like promises,
815 futures are essentially proxies that can be queried to obtain the value
816 of the enclosed expression:
819 (touch (future (+ 2 3)))
823 However, unlike promises, the expression associated with a future may be
824 evaluated on another CPU core, should one be available. This supports
825 @dfn{fine-grain parallelism}, because even relatively small computations
826 can be embedded in futures. Consider this sequential code:
829 (define (find-prime lst1 lst2)
830 (or (find prime? lst1)
834 The two arms of @code{or} are potentially computation-intensive. They
835 are independent of one another, yet, they are evaluated sequentially
836 when the first one returns @code{#f}. Using futures, one could rewrite
840 (define (find-prime lst1 lst2)
841 (let ((f (future (find prime? lst2))))
842 (or (find prime? lst1)
846 This preserves the semantics of @code{find-prime}. On a multi-core
847 machine, though, the computation of @code{(find prime? lst2)} may be
848 done in parallel with that of the other @code{find} call, which can
849 reduce the execution time of @code{find-prime}.
851 Note that futures are intended for the evaluation of purely functional
852 expressions. Expressions that have side-effects or rely on I/O may
853 require additional care, such as explicit synchronization
854 (@pxref{Mutexes and Condition Variables}).
856 Guile's futures are implemented on top of POSIX threads
857 (@pxref{Threads}). Internally, a fixed-size pool of threads is used to
858 evaluate futures, such that offloading the evaluation of an expression
859 to another thread doesn't incur thread creation costs. By default, the
860 pool contains one thread per available CPU core, minus one, to account
861 for the main thread. The number of available CPU cores is determined
862 using @code{current-processor-count} (@pxref{Processes}).
864 @deffn {Scheme Syntax} future exp
865 Return a future for expression @var{exp}. This is equivalent to:
868 (make-future (lambda () exp))
872 @deffn {Scheme Procedure} make-future thunk
873 Return a future for @var{thunk}, a zero-argument procedure.
875 This procedure returns immediately. Execution of @var{thunk} may begin
876 in parallel with the calling thread's computations, if idle CPU cores
877 are available, or it may start when @code{touch} is invoked on the
880 If the execution of @var{thunk} throws an exception, that exception will
881 be re-thrown when @code{touch} is invoked on the returned future.
884 @deffn {Scheme Procedure} future? obj
885 Return @code{#t} if @var{obj} is a future.
888 @deffn {Scheme Procedure} touch f
889 Return the result of the expression embedded in future @var{f}.
891 If the result was already computed in parallel, @code{touch} returns
892 instantaneously. Otherwise, it waits for the computation to complete,
893 if it already started, or initiates it.
898 @subsection Parallel forms
899 @cindex parallel forms
901 The functions described in this section are available from
904 (use-modules (ice-9 threads))
907 @deffn syntax parallel expr1 @dots{} exprN
908 Evaluate each @var{expr} expression in parallel, each in its own thread.
909 Return the results as a set of @var{N} multiple values
910 (@pxref{Multiple Values}).
913 @deffn syntax letpar ((var1 expr1) @dots{} (varN exprN)) body@dots{}
914 Evaluate each @var{expr} in parallel, each in its own thread, then bind
915 the results to the corresponding @var{var} variables and evaluate
918 @code{letpar} is like @code{let} (@pxref{Local Bindings}), but all the
919 expressions for the bindings are evaluated in parallel.
922 @deffn {Scheme Procedure} par-map proc lst1 @dots{} lstN
923 @deffnx {Scheme Procedure} par-for-each proc lst1 @dots{} lstN
924 Call @var{proc} on the elements of the given lists. @code{par-map}
925 returns a list comprising the return values from @var{proc}.
926 @code{par-for-each} returns an unspecified value, but waits for all
929 The @var{proc} calls are @code{(@var{proc} @var{elem1} @dots{}
930 @var{elemN})}, where each @var{elem} is from the corresponding
931 @var{lst}. Each @var{lst} must be the same length. The calls are
932 made in parallel, each in its own thread.
934 These functions are like @code{map} and @code{for-each} (@pxref{List
935 Mapping}), but make their @var{proc} calls in parallel.
938 @deffn {Scheme Procedure} n-par-map n proc lst1 @dots{} lstN
939 @deffnx {Scheme Procedure} n-par-for-each n proc lst1 @dots{} lstN
940 Call @var{proc} on the elements of the given lists, in the same way as
941 @code{par-map} and @code{par-for-each} above, but use no more than
942 @var{n} threads at any one time. The order in which calls are
943 initiated within that threads limit is unspecified.
945 These functions are good for controlling resource consumption if
946 @var{proc} calls might be costly, or if there are many to be made. On
947 a dual-CPU system for instance @math{@var{n}=4} might be enough to
948 keep the CPUs utilized, and not consume too much memory.
951 @deffn {Scheme Procedure} n-for-each-par-map n sproc pproc lst1 @dots{} lstN
952 Apply @var{pproc} to the elements of the given lists, and apply
953 @var{sproc} to each result returned by @var{pproc}. The final return
954 value is unspecified, but all calls will have been completed before
957 The calls made are @code{(@var{sproc} (@var{pproc} @var{elem1} @dots{}
958 @var{elemN}))}, where each @var{elem} is from the corresponding
959 @var{lst}. Each @var{lst} must have the same number of elements.
961 The @var{pproc} calls are made in parallel, in separate threads. No more
962 than @var{n} threads are used at any one time. The order in which
963 @var{pproc} calls are initiated within that limit is unspecified.
965 The @var{sproc} calls are made serially, in list element order, one at
966 a time. @var{pproc} calls on later elements may execute in parallel
967 with the @var{sproc} calls. Exactly which thread makes each
968 @var{sproc} call is unspecified.
970 This function is designed for individual calculations that can be done
971 in parallel, but with results needing to be handled serially, for
972 instance to write them to a file. The @var{n} limit on threads
973 controls system resource usage when there are many calculations or
974 when they might be costly.
976 It will be seen that @code{n-for-each-par-map} is like a combination
977 of @code{n-par-map} and @code{for-each},
980 (for-each sproc (n-par-map n pproc lst1 ... lstN))
984 But the actual implementation is more efficient since each @var{sproc}
985 call, in turn, can be initiated once the relevant @var{pproc} call has
986 completed, it doesn't need to wait for all to finish.
992 @c TeX-master: "guile.texi"