2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
9 @section Threads, Mutexes, Asyncs and Dynamic Roots
11 [FIXME: This is pasted in from Tom Lord's original guile.texi chapter
12 plus the Cygnus programmer's manual; it should be *very* carefully
13 reviewed and largely reorganized.]
16 * Arbiters:: Synchronization primitives.
17 * Asyncs:: Asynchronous procedure invocation.
18 * Continuation Barriers:: Protection from non-local control flow.
19 * Threads:: Multiple threads of execution.
20 * Mutexes and Condition Variables:: Synchronization primitives.
21 * Blocking:: How to block properly in guile mode.
22 * Critical Sections:: Avoiding concurrency and reentries.
23 * Fluids and Dynamic States:: Thread-local variables, etc.
24 * Parallel Forms:: Parallel execution of forms.
32 Arbiters are synchronization objects, they can be used by threads to
33 control access to a shared resource. An arbiter can be locked to
34 indicate a resource is in use, and unlocked when done.
36 An arbiter is like a light-weight mutex (@pxref{Mutexes and Condition
37 Variables}). It uses less memory and may be faster, but there's no
38 way for a thread to block waiting on an arbiter, it can only test and
39 get the status returned.
41 @deffn {Scheme Procedure} make-arbiter name
42 @deffnx {C Function} scm_make_arbiter (name)
43 Return an object of type arbiter and name @var{name}. Its
44 state is initially unlocked. Arbiters are a way to achieve
45 process synchronization.
48 @deffn {Scheme Procedure} try-arbiter arb
49 @deffnx {C Function} scm_try_arbiter (arb)
50 @deffnx {C Function} scm_try_arbiter (arb)
51 If @var{arb} is unlocked, then lock it and return @code{#t}.
52 If @var{arb} is already locked, then do nothing and return
56 @deffn {Scheme Procedure} release-arbiter arb
57 @deffnx {C Function} scm_release_arbiter (arb)
58 If @var{arb} is locked, then unlock it and return @code{#t}. If
59 @var{arb} is already unlocked, then do nothing and return @code{#f}.
61 Typical usage is for the thread which locked an arbiter to later
62 release it, but that's not required, any thread can release it.
73 Asyncs are a means of deferring the excution of Scheme code until it is
76 Guile provides two kinds of asyncs that share the basic concept but are
77 otherwise quite different: system asyncs and user asyncs. System asyncs
78 are integrated into the core of Guile and are executed automatically
79 when the system is in a state to allow the execution of Scheme code.
80 For example, it is not possible to execute Scheme code in a POSIX signal
81 handler, but such a signal handler can queue a system async to be
82 executed in the near future, when it is safe to do so.
84 System asyncs can also be queued for threads other than the current one.
85 This way, you can cause threads to asynchronously execute arbitrary
88 User asyncs offer a convenient means of queueing procedures for future
89 execution and triggering this execution. They will not be executed
98 @subsubsection System asyncs
100 To cause the future asynchronous execution of a procedure in a given
101 thread, use @code{system-async-mark}.
103 Automatic invocation of system asyncs can be temporarily disabled by
104 calling @code{call-with-blocked-asyncs}. This function works by
105 temporarily increasing the @emph{async blocking level} of the current
106 thread while a given procedure is running. The blocking level starts
107 out at zero, and whenever a safe point is reached, a blocking level
108 greater than zero will prevent the execution of queued asyncs.
110 Analogously, the procedure @code{call-with-unblocked-asyncs} will
111 temporarily decrease the blocking level of the current thread. You
112 can use it when you want to disable asyncs by default and only allow
115 In addition to the C versions of @code{call-with-blocked-asyncs} and
116 @code{call-with-unblocked-asyncs}, C code can use
117 @code{scm_dynwind_block_asyncs} and @code{scm_dynwind_unblock_asyncs}
118 inside a @dfn{dynamic context} (@pxref{Dynamic Wind}) to block or
119 unblock system asyncs temporarily.
121 @deffn {Scheme Procedure} system-async-mark proc [thread]
122 @deffnx {C Function} scm_system_async_mark (proc)
123 @deffnx {C Function} scm_system_async_mark_for_thread (proc, thread)
124 Mark @var{proc} (a procedure with zero arguments) for future execution
125 in @var{thread}. When @var{proc} has already been marked for
126 @var{thread} but has not been executed yet, this call has no effect.
127 When @var{thread} is omitted, the thread that called
128 @code{system-async-mark} is used.
130 This procedure is not safe to be called from signal handlers. Use
131 @code{scm_sigaction} or @code{scm_sigaction_for_thread} to install
135 @c FIXME: The use of @deffnx for scm_c_call_with_blocked_asyncs and
136 @c scm_c_call_with_unblocked_asyncs puts "void" into the function
137 @c index. Would prefer to use @deftypefnx if makeinfo allowed that,
138 @c or a @deftypefn with an empty return type argument if it didn't
139 @c introduce an extra space.
141 @deffn {Scheme Procedure} call-with-blocked-asyncs proc
142 @deffnx {C Function} scm_call_with_blocked_asyncs (proc)
143 @deffnx {C Function} {void *} scm_c_call_with_blocked_asyncs (void * (*proc) (void *data), void *data)
144 @findex scm_c_call_with_blocked_asyncs
145 Call @var{proc} and block the execution of system asyncs by one level
146 for the current thread while it is running. Return the value returned
147 by @var{proc}. For the first two variants, call @var{proc} with no
148 arguments; for the third, call it with @var{data}.
151 @deffn {Scheme Procedure} call-with-unblocked-asyncs proc
152 @deffnx {C Function} scm_call_with_unblocked_asyncs (proc)
153 @deffnx {C Function} {void *} scm_c_call_with_unblocked_asyncs (void *(*p) (void *d), void *d)
154 @findex scm_c_call_with_unblocked_asyncs
155 Call @var{proc} and unblock the execution of system asyncs by one
156 level for the current thread while it is running. Return the value
157 returned by @var{proc}. For the first two variants, call @var{proc}
158 with no arguments; for the third, call it with @var{data}.
161 @deftypefn {C Function} void scm_dynwind_block_asyncs ()
162 This function must be used inside a pair of calls to
163 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
164 Wind}). During the dynwind context, asyncs are blocked by one level.
167 @deftypefn {C Function} void scm_dynwind_unblock_asyncs ()
168 This function must be used inside a pair of calls to
169 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
170 Wind}). During the dynwind context, asyncs are unblocked by one
175 @subsubsection User asyncs
177 A user async is a pair of a thunk (a parameterless procedure) and a
178 mark. Setting the mark on a user async will cause the thunk to be
179 executed when the user async is passed to @code{run-asyncs}. Setting
180 the mark more than once is satisfied by one execution of the thunk.
182 User asyncs are created with @code{async}. They are marked with
185 @deffn {Scheme Procedure} async thunk
186 @deffnx {C Function} scm_async (thunk)
187 Create a new user async for the procedure @var{thunk}.
190 @deffn {Scheme Procedure} async-mark a
191 @deffnx {C Function} scm_async_mark (a)
192 Mark the user async @var{a} for future execution.
195 @deffn {Scheme Procedure} run-asyncs list_of_a
196 @deffnx {C Function} scm_run_asyncs (list_of_a)
197 Execute all thunks from the marked asyncs of the list @var{list_of_a}.
200 @node Continuation Barriers
201 @subsection Continuation Barriers
203 The non-local flow of control caused by continuations might sometimes
204 not be wanted. You can use @code{with-continuation-barrier} etc to
205 errect fences that continuations can not pass.
207 @deffn {Scheme Procedure} with-continuation-barrier proc
208 @deffnx {C Function} scm_with_continuation_barrier (proc)
209 Call @var{proc} and return its result. Do not allow the invocation of
210 continuations that would leave or enter the dynamic extent of the call
211 to @code{with-continuation-barrier}. Such an attempt causes an error
214 Throws (such as errors) that are not caught from within @var{proc} are
215 caught by @code{with-continuation-barrier}. In that case, a short
216 message is printed to the current error port and @code{#f} is returned.
218 Thus, @code{with-continuation-barrier} returns exactly once.
221 @deftypefn {C Function} {void *} scm_c_with_continuation_barrier (void *(*func) (void *), void *data)
222 Like @code{scm_with_continuation_barrier} but call @var{func} on
223 @var{data}. When an error is caught, @code{NULL} is returned.
229 @cindex Guile threads
230 @cindex POSIX threads
232 @deffn {Scheme Procedure} all-threads
233 @deffnx {C Function} scm_all_threads ()
234 Return a list of all threads.
237 @deffn {Scheme Procedure} current-thread
238 @deffnx {C Function} scm_current_thread ()
239 Return the thread that called this function.
242 @c begin (texi-doc-string "guile" "call-with-new-thread")
243 @deffn {Scheme Procedure} call-with-new-thread thunk [handler]
244 Call @code{thunk} in a new thread and with a new dynamic state,
245 returning the new thread. The procedure @var{thunk} is called via
246 @code{with-continuation-barrier}.
248 When @var{handler} is specified, then @var{thunk} is called from
249 within a @code{catch} with tag @code{#t} that has @var{handler} as its
250 handler. This catch is established inside the continuation barrier.
252 Once @var{thunk} or @var{handler} returns, the return value is made
253 the @emph{exit value} of the thread and the thread is terminated.
256 @deftypefn {C Function} SCM scm_spawn_thread (scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data)
257 Call @var{body} in a new thread, passing it @var{body_data}, returning
258 the new thread. The function @var{body} is called via
259 @code{scm_c_with_continuation_barrier}.
261 When @var{handler} is non-@code{NULL}, @var{body} is called via
262 @code{scm_internal_catch} with tag @code{SCM_BOOL_T} that has
263 @var{handler} and @var{handler_data} as the handler and its data. This
264 catch is established inside the continuation barrier.
266 Once @var{body} or @var{handler} returns, the return value is made the
267 @emph{exit value} of the thread and the thread is terminated.
270 @deffn {Scheme Procedure} thread? obj
271 @deffnx {C Function} scm_thread_p (obj)
272 Return @code{#t} iff @var{obj} is a thread; otherwise, return
276 @c begin (texi-doc-string "guile" "join-thread")
277 @deffn {Scheme Procedure} join-thread thread [timeout [timeoutval]]
278 @deffnx {C Function} scm_join_thread (thread)
279 @deffnx {C Function} scm_join_thread_timed (thread, timeout, timeoutval)
280 Wait for @var{thread} to terminate and return its exit value. Threads
281 that have not been created with @code{call-with-new-thread} or
282 @code{scm_spawn_thread} have an exit value of @code{#f}. When
283 @var{timeout} is given, it specifies a point in time where the waiting
284 should be aborted. It can be either an integer as returned by
285 @code{current-time} or a pair as returned by @code{gettimeofday}.
286 When the waiting is aborted, @var{timeoutval} is returned (if it is
287 specified; @code{#f} is returned otherwise).
290 @deffn {Scheme Procedure} thread-exited? thread
291 @deffnx {C Function} scm_thread_exited_p (thread)
292 Return @code{#t} iff @var{thread} has exited.
295 @c begin (texi-doc-string "guile" "yield")
296 @deffn {Scheme Procedure} yield
297 If one or more threads are waiting to execute, calling yield forces an
298 immediate context switch to one of them. Otherwise, yield has no effect.
301 @deffn {Scheme Procedure} cancel-thread thread
302 @deffnx {C Function} scm_cancel_thread (thread)
303 Asynchronously notify @var{thread} to exit. Immediately after
304 receiving this notification, @var{thread} will call its cleanup handler
305 (if one has been set) and then terminate, aborting any evaluation that
308 Because Guile threads are isomorphic with POSIX threads, @var{thread}
309 will not receive its cancellation signal until it reaches a cancellation
310 point. See your operating system's POSIX threading documentation for
311 more information on cancellation points; note that in Guile, unlike
312 native POSIX threads, a thread can receive a cancellation notification
313 while attempting to lock a mutex.
316 @deffn {Scheme Procedure} set-thread-cleanup! thread proc
317 @deffnx {C Function} scm_set_thread_cleanup_x (thread, proc)
318 Set @var{proc} as the cleanup handler for the thread @var{thread}.
319 @var{proc}, which must be a thunk, will be called when @var{thread}
320 exits, either normally or by being canceled. Thread cleanup handlers
321 can be used to perform useful tasks like releasing resources, such as
322 locked mutexes, when thread exit cannot be predicted.
324 The return value of @var{proc} will be set as the @emph{exit value} of
327 To remove a cleanup handler, pass @code{#f} for @var{proc}.
330 @deffn {Scheme Procedure} thread-cleanup thread
331 @deffnx {C Function} scm_thread_cleanup (thread)
332 Return the cleanup handler currently installed for the thread
333 @var{thread}. If no cleanup handler is currently installed,
334 thread-cleanup returns @code{#f}.
337 Higher level thread procedures are available by loading the
338 @code{(ice-9 threads)} module. These provide standardized
341 @deffn macro make-thread proc [args@dots{}]
342 Apply @var{proc} to @var{args} in a new thread formed by
343 @code{call-with-new-thread} using a default error handler that display
344 the error to the current error port. The @var{args@dots{}}
345 expressions are evaluated in the new thread.
348 @deffn macro begin-thread first [rest@dots{}]
349 Evaluate forms @var{first} and @var{rest} in a new thread formed by
350 @code{call-with-new-thread} using a default error handler that display
351 the error to the current error port.
354 @node Mutexes and Condition Variables
355 @subsection Mutexes and Condition Variables
357 @cindex condition variable
359 A mutex is a thread synchronization object, it can be used by threads
360 to control access to a shared resource. A mutex can be locked to
361 indicate a resource is in use, and other threads can then block on the
362 mutex to wait for the resource (or can just test and do something else
363 if not available). ``Mutex'' is short for ``mutual exclusion''.
365 There are two types of mutexes in Guile, ``standard'' and
366 ``recursive''. They're created by @code{make-mutex} and
367 @code{make-recursive-mutex} respectively, the operation functions are
370 Note that for both types of mutex there's no protection against a
371 ``deadly embrace''. For instance if one thread has locked mutex A and
372 is waiting on mutex B, but another thread owns B and is waiting on A,
373 then an endless wait will occur (in the current implementation).
374 Acquiring requisite mutexes in a fixed order (like always A before B)
375 in all threads is one way to avoid such problems.
378 @deffn {Scheme Procedure} make-mutex . flags
379 @deffnx {C Function} scm_make_mutex ()
380 @deffnx {C Function} scm_make_mutex_with_flags (SCM flags)
381 Return a new mutex. It is initially unlocked. If @var{flags} is
382 specified, it must be a list of symbols specifying configuration flags
383 for the newly-created mutex. The supported flags are:
385 @item unchecked-unlock
386 Unless this flag is present, a call to `unlock-mutex' on the returned
387 mutex when it is already unlocked will cause an error to be signalled.
389 @item allow-external-unlock
390 Allow the returned mutex to be unlocked by the calling thread even if
391 it was originally locked by a different thread.
394 The returned mutex will be recursive.
399 @deffn {Scheme Procedure} mutex? obj
400 @deffnx {C Function} scm_mutex_p (obj)
401 Return @code{#t} iff @var{obj} is a mutex; otherwise, return
405 @deffn {Scheme Procedure} make-recursive-mutex
406 @deffnx {C Function} scm_make_recursive_mutex ()
407 Create a new recursive mutex. It is initially unlocked. Calling this
408 function is equivalent to calling `make-mutex' and specifying the
409 @code{recursive} flag.
412 @deffn {Scheme Procedure} lock-mutex mutex [timeout [owner]]
413 @deffnx {C Function} scm_lock_mutex (mutex)
414 @deffnx {C Function} scm_lock_mutex_timed (mutex, timeout, owner)
415 Lock @var{mutex}. If the mutex is already locked, then block and
416 return only when @var{mutex} has been acquired.
418 When @var{timeout} is given, it specifies a point in time where the
419 waiting should be aborted. It can be either an integer as returned
420 by @code{current-time} or a pair as returned by @code{gettimeofday}.
421 When the waiting is aborted, @code{#f} is returned.
423 When @var{owner} is given, it specifies an owner for @var{mutex} other
424 than the calling thread. @var{owner} may also be @code{#f},
425 indicating that the mutex should be locked but left unowned.
427 For standard mutexes (@code{make-mutex}), and error is signalled if
428 the thread has itself already locked @var{mutex}.
430 For a recursive mutex (@code{make-recursive-mutex}), if the thread has
431 itself already locked @var{mutex}, then a further @code{lock-mutex}
432 call increments the lock count. An additional @code{unlock-mutex}
433 will be required to finally release.
435 If @var{mutex} was locked by a thread that exited before unlocking it,
436 the next attempt to lock @var{mutex} will succeed, but
437 @code{abandoned-mutex-error} will be signalled.
439 When a system async (@pxref{System asyncs}) is activated for a thread
440 blocked in @code{lock-mutex}, the wait is interrupted and the async is
441 executed. When the async returns, the wait resumes.
444 @deftypefn {C Function} void scm_dynwind_lock_mutex (SCM mutex)
445 Arrange for @var{mutex} to be locked whenever the current dynwind
446 context is entered and to be unlocked when it is exited.
449 @deffn {Scheme Procedure} try-mutex mx
450 @deffnx {C Function} scm_try_mutex (mx)
451 Try to lock @var{mutex} as per @code{lock-mutex}. If @var{mutex} can
452 be acquired immediately then this is done and the return is @code{#t}.
453 If @var{mutex} is locked by some other thread then nothing is done and
454 the return is @code{#f}.
457 @deffn {Scheme Procedure} unlock-mutex mutex [condvar [timeout]]
458 @deffnx {C Function} scm_unlock_mutex (mutex)
459 @deffnx {C Function} scm_unlock_mutex_timed (mutex, condvar, timeout)
460 Unlock @var{mutex}. An error is signalled if @var{mutex} is not locked
461 and was not created with the @code{unchecked-unlock} flag set, or if
462 @var{mutex} is locked by a thread other than the calling thread and was
463 not created with the @code{allow-external-unlock} flag set.
465 If @var{condvar} is given, it specifies a condition variable upon
466 which the calling thread will wait to be signalled before returning.
467 (This behavior is very similar to that of
468 @code{wait-condition-variable}, except that the mutex is left in an
469 unlocked state when the function returns.)
471 When @var{timeout} is also given, it specifies a point in time where
472 the waiting should be aborted. It can be either an integer as
473 returned by @code{current-time} or a pair as returned by
474 @code{gettimeofday}. When the waiting is aborted, @code{#f} is
475 returned. Otherwise the function returns @code{#t}.
478 @deffn {Scheme Procedure} mutex-owner mutex
479 @deffnx {C Function} scm_mutex_owner (mutex)
480 Return the current owner of @var{mutex}, in the form of a thread or
481 @code{#f} (indicating no owner). Note that a mutex may be unowned but
485 @deffn {Scheme Procedure} mutex-level mutex
486 @deffnx {C Function} scm_mutex_level (mutex)
487 Return the current lock level of @var{mutex}. If @var{mutex} is
488 currently unlocked, this value will be 0; otherwise, it will be the
489 number of times @var{mutex} has been recursively locked by its current
493 @deffn {Scheme Procedure} mutex-locked? mutex
494 @deffnx {C Function} scm_mutex_locked_p (mutex)
495 Return @code{#t} if @var{mutex} is locked, regardless of ownership;
496 otherwise, return @code{#f}.
499 @deffn {Scheme Procedure} make-condition-variable
500 @deffnx {C Function} scm_make_condition_variable ()
501 Return a new condition variable.
504 @deffn {Scheme Procedure} condition-variable? obj
505 @deffnx {C Function} scm_condition_variable_p (obj)
506 Return @code{#t} iff @var{obj} is a condition variable; otherwise,
510 @deffn {Scheme Procedure} wait-condition-variable condvar mutex [time]
511 @deffnx {C Function} scm_wait_condition_variable (condvar, mutex, time)
512 Wait until @var{condvar} has been signalled. While waiting,
513 @var{mutex} is atomically unlocked (as with @code{unlock-mutex}) and
514 is locked again when this function returns. When @var{time} is given,
515 it specifies a point in time where the waiting should be aborted. It
516 can be either a integer as returned by @code{current-time} or a pair
517 as returned by @code{gettimeofday}. When the waiting is aborted,
518 @code{#f} is returned. When the condition variable has in fact been
519 signalled, @code{#t} is returned. The mutex is re-locked in any case
520 before @code{wait-condition-variable} returns.
522 When a system async is activated for a thread that is blocked in a
523 call to @code{wait-condition-variable}, the waiting is interrupted,
524 the mutex is locked, and the async is executed. When the async
525 returns, the mutex is unlocked again and the waiting is resumed. When
526 the thread block while re-acquiring the mutex, execution of asyncs is
530 @deffn {Scheme Procedure} signal-condition-variable condvar
531 @deffnx {C Function} scm_signal_condition_variable (condvar)
532 Wake up one thread that is waiting for @var{condvar}.
535 @deffn {Scheme Procedure} broadcast-condition-variable condvar
536 @deffnx {C Function} scm_broadcast_condition_variable (condvar)
537 Wake up all threads that are waiting for @var{condvar}.
541 The following are higher level operations on mutexes. These are
545 (use-modules (ice-9 threads))
548 @deffn macro with-mutex mutex [body@dots{}]
549 Lock @var{mutex}, evaluate the @var{body} forms, then unlock
550 @var{mutex}. The return value is the return from the last @var{body}
553 The lock, body and unlock form the branches of a @code{dynamic-wind}
554 (@pxref{Dynamic Wind}), so @var{mutex} is automatically unlocked if an
555 error or new continuation exits @var{body}, and is re-locked if
556 @var{body} is re-entered by a captured continuation.
559 @deffn macro monitor body@dots{}
560 Evaluate the @var{body} forms, with a mutex locked so only one thread
561 can execute that code at any one time. The return value is the return
562 from the last @var{body} form.
564 Each @code{monitor} form has its own private mutex and the locking and
565 evaluation is as per @code{with-mutex} above. A standard mutex
566 (@code{make-mutex}) is used, which means @var{body} must not
567 recursively re-enter the @code{monitor} form.
569 The term ``monitor'' comes from operating system theory, where it
570 means a particular bit of code managing access to some resource and
571 which only ever executes on behalf of one process at any one time.
576 @subsection Blocking in Guile Mode
578 A thread must not block outside of a libguile function while it is in
579 guile mode. The following functions can be used to temporily leave
580 guile mode or to perform some common blocking operations in a supported
583 @deftypefn {C Function} {void *} scm_without_guile (void *(*func) (void *), void *data)
584 Leave guile mode, call @var{func} on @var{data}, enter guile mode and
585 return the result of calling @var{func}.
587 While a thread has left guile mode, it must not call any libguile
588 functions except @code{scm_with_guile} or @code{scm_without_guile} and
589 must not use any libguile macros. Also, local variables of type
590 @code{SCM} that are allocated while not in guile mode are not
591 protected from the garbage collector.
593 When used from non-guile mode, calling @code{scm_without_guile} is
594 still allowed: it simply calls @var{func}. In that way, you can leave
595 guile mode without having to know whether the current thread is in
599 @deftypefn {C Function} int scm_pthread_mutex_lock (pthread_mutex_t *mutex)
600 Like @code{pthread_mutex_lock}, but leaves guile mode while waiting for
604 @deftypefn {C Function} int scm_pthread_cond_wait (pthread_cond_t *cond, pthread_mutex_t *mutex)
605 @deftypefnx {C Function} int scm_pthread_cond_timedwait (pthread_cond_t *cond, pthread_mutex_t *mutex, struct timespec *abstime)
606 Like @code{pthread_cond_wait} and @code{pthread_cond_timedwait}, but
607 leaves guile mode while waiting for the condition variable.
610 @deftypefn {C Function} int scm_std_select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
611 Like @code{select} but leaves guile mode while waiting. Also, the
612 delivery of a system async causes this function to be interrupted with
613 error code @code{EINTR}.
616 @deftypefn {C Function} {unsigned int} scm_std_sleep ({unsigned int} seconds)
617 Like @code{sleep}, but leaves guile mode while sleeping. Also, the
618 delivery of a system async causes this function to be interrupted.
621 @deftypefn {C Function} {unsigned long} scm_std_usleep ({unsigned long} usecs)
622 Like @code{usleep}, but leaves guile mode while sleeping. Also, the
623 delivery of a system async causes this function to be interrupted.
627 @node Critical Sections
628 @subsection Critical Sections
630 @deffn {C Macro} SCM_CRITICAL_SECTION_START
631 @deffnx {C Macro} SCM_CRITICAL_SECTION_END
632 These two macros can be used to delimit a critical section.
633 Syntactically, they are both statements and need to be followed
634 immediately by a semicolon.
636 Executing @code{SCM_CRITICAL_SECTION_START} will lock a recursive
637 mutex and block the executing of system asyncs. Executing
638 @code{SCM_CRITICAL_SECTION_END} will unblock the execution of system
639 asyncs and unlock the mutex. Thus, the code that executes between
640 these two macros can only be executed in one thread at any one time
641 and no system asyncs will run. However, because the mutex is a
642 recursive one, the code might still be reentered by the same thread.
643 You must either allow for this or avoid it, both by careful coding.
645 On the other hand, critical sections delimited with these macros can
646 be nested since the mutex is recursive.
648 You must make sure that for each @code{SCM_CRITICAL_SECTION_START},
649 the corresponding @code{SCM_CRITICAL_SECTION_END} is always executed.
650 This means that no non-local exit (such as a signalled error) might
654 @deftypefn {C Function} void scm_dynwind_critical_section (SCM mutex)
655 Call @code{scm_dynwind_lock_mutex} on @var{mutex} and call
656 @code{scm_dynwind_block_asyncs}. When @var{mutex} is false, a recursive
657 mutex provided by Guile is used instead.
659 The effect of a call to @code{scm_dynwind_critical_section} is that
660 the current dynwind context (@pxref{Dynamic Wind}) turns into a
661 critical section. Because of the locked mutex, no second thread can
662 enter it concurrently and because of the blocked asyncs, no system
663 async can reenter it from the current thread.
665 When the current thread reenters the critical section anyway, the kind
666 of @var{mutex} determines what happens: When @var{mutex} is recursive,
667 the reentry is allowed. When it is a normal mutex, an error is
672 @node Fluids and Dynamic States
673 @subsection Fluids and Dynamic States
677 A @emph{fluid} is an object that can store one value per @emph{dynamic
678 state}. Each thread has a current dynamic state, and when accessing a
679 fluid, this current dynamic state is used to provide the actual value.
680 In this way, fluids can be used for thread local storage, but they are
681 in fact more flexible: dynamic states are objects of their own and can
682 be made current for more than one thread at the same time, or only be
683 made current temporarily, for example.
685 Fluids can also be used to simulate the desirable effects of
686 dynamically scoped variables. Dynamically scoped variables are useful
687 when you want to set a variable to a value during some dynamic extent
688 in the execution of your program and have them revert to their
689 original value when the control flow is outside of this dynamic
690 extent. See the description of @code{with-fluids} below for details.
692 New fluids are created with @code{make-fluid} and @code{fluid?} is
693 used for testing whether an object is actually a fluid. The values
694 stored in a fluid can be accessed with @code{fluid-ref} and
697 @deffn {Scheme Procedure} make-fluid
698 @deffnx {C Function} scm_make_fluid ()
699 Return a newly created fluid.
700 Fluids are objects that can hold one
701 value per dynamic state. That is, modifications to this value are
702 only visible to code that executes with the same dynamic state as
703 the modifying code. When a new dynamic state is constructed, it
704 inherits the values from its parent. Because each thread normally executes
705 with its own dynamic state, you can use fluids for thread local storage.
708 @deffn {Scheme Procedure} fluid? obj
709 @deffnx {C Function} scm_fluid_p (obj)
710 Return @code{#t} iff @var{obj} is a fluid; otherwise, return
714 @deffn {Scheme Procedure} fluid-ref fluid
715 @deffnx {C Function} scm_fluid_ref (fluid)
716 Return the value associated with @var{fluid} in the current
717 dynamic root. If @var{fluid} has not been set, then return
721 @deffn {Scheme Procedure} fluid-set! fluid value
722 @deffnx {C Function} scm_fluid_set_x (fluid, value)
723 Set the value associated with @var{fluid} in the current dynamic root.
726 @code{with-fluids*} temporarily changes the values of one or more fluids,
727 so that the given procedure and each procedure called by it access the
728 given values. After the procedure returns, the old values are restored.
730 @deffn {Scheme Procedure} with-fluid* fluid value thunk
731 @deffnx {C Function} scm_with_fluid (fluid, value, thunk)
732 Set @var{fluid} to @var{value} temporarily, and call @var{thunk}.
733 @var{thunk} must be a procedure with no argument.
736 @deffn {Scheme Procedure} with-fluids* fluids values thunk
737 @deffnx {C Function} scm_with_fluids (fluids, values, thunk)
738 Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
739 @var{fluids} must be a list of fluids and @var{values} must be the
740 same number of their values to be applied. Each substitution is done
741 in the order given. @var{thunk} must be a procedure with no argument.
742 it is called inside a @code{dynamic-wind} and the fluids are
743 set/restored when control enter or leaves the established dynamic
747 @deffn {Scheme Macro} with-fluids ((fluid value) ...) body...
748 Execute @var{body...} while each @var{fluid} is set to the
749 corresponding @var{value}. Both @var{fluid} and @var{value} are
750 evaluated and @var{fluid} must yield a fluid. @var{body...} is
751 executed inside a @code{dynamic-wind} and the fluids are set/restored
752 when control enter or leaves the established dynamic extent.
755 @deftypefn {C Function} SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)
756 @deftypefnx {C Function} SCM scm_c_with_fluid (SCM fluid, SCM val, SCM (*cproc)(void *), void *data)
757 The function @code{scm_c_with_fluids} is like @code{scm_with_fluids}
758 except that it takes a C function to call instead of a Scheme thunk.
760 The function @code{scm_c_with_fluid} is similar but only allows one
761 fluid to be set instead of a list.
764 @deftypefn {C Function} void scm_dynwind_fluid (SCM fluid, SCM val)
765 This function must be used inside a pair of calls to
766 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
767 Wind}). During the dynwind context, the fluid @var{fluid} is set to
770 More precisely, the value of the fluid is swapped with a `backup'
771 value whenever the dynwind context is entered or left. The backup
772 value is initialized with the @var{val} argument.
775 @deffn {Scheme Procedure} make-dynamic-state [parent]
776 @deffnx {C Function} scm_make_dynamic_state (parent)
777 Return a copy of the dynamic state object @var{parent}
778 or of the current dynamic state when @var{parent} is omitted.
781 @deffn {Scheme Procedure} dynamic-state? obj
782 @deffnx {C Function} scm_dynamic_state_p (obj)
783 Return @code{#t} if @var{obj} is a dynamic state object;
784 return @code{#f} otherwise.
787 @deftypefn {C Procedure} int scm_is_dynamic_state (SCM obj)
788 Return non-zero if @var{obj} is a dynamic state object;
789 return zero otherwise.
792 @deffn {Scheme Procedure} current-dynamic-state
793 @deffnx {C Function} scm_current_dynamic_state ()
794 Return the current dynamic state object.
797 @deffn {Scheme Procedure} set-current-dynamic-state state
798 @deffnx {C Function} scm_set_current_dynamic_state (state)
799 Set the current dynamic state object to @var{state}
800 and return the previous current dynamic state object.
803 @deffn {Scheme Procedure} with-dynamic-state state proc
804 @deffnx {C Function} scm_with_dynamic_state (state, proc)
805 Call @var{proc} while @var{state} is the current dynamic
809 @deftypefn {C Procedure} void scm_dynwind_current_dynamic_state (SCM state)
810 Set the current dynamic state to @var{state} for the current dynwind
814 @deftypefn {C Procedure} {void *} scm_c_with_dynamic_state (SCM state, void *(*func)(void *), void *data)
815 Like @code{scm_with_dynamic_state}, but call @var{func} with
820 @c @subsection Futures
823 @c -- Futures are disabled for the time being, see futures.h for an
826 @c Futures are a convenient way to run a calculation in a new thread, and
827 @c only wait for the result when it's actually needed.
829 @c Futures are similar to promises (@pxref{Delayed Evaluation}), in that
830 @c they allow mainline code to continue immediately. But @code{delay}
831 @c doesn't evaluate at all until forced, whereas @code{future} starts
832 @c immediately in a new thread.
834 @c @deffn {syntax} future expr
835 @c Begin evaluating @var{expr} in a new thread, and return a ``future''
836 @c object representing the calculation.
839 @c @deffn {Scheme Procedure} make-future thunk
840 @c @deffnx {C Function} scm_make_future (thunk)
841 @c Begin evaluating the call @code{(@var{thunk})} in a new thread, and
842 @c return a ``future'' object representing the calculation.
845 @c @deffn {Scheme Procedure} future-ref f
846 @c @deffnx {C Function} scm_future_ref (f)
847 @c Return the value computed by the future @var{f}. If @var{f} has not
848 @c yet finished executing then wait for it to do so.
853 @subsection Parallel forms
854 @cindex parallel forms
856 The functions described in this section are available from
859 (use-modules (ice-9 threads))
862 @deffn syntax parallel expr1 @dots{} exprN
863 Evaluate each @var{expr} expression in parallel, each in its own thread.
864 Return the results as a set of @var{N} multiple values
865 (@pxref{Multiple Values}).
868 @deffn syntax letpar ((var1 expr1) @dots{} (varN exprN)) body@dots{}
869 Evaluate each @var{expr} in parallel, each in its own thread, then bind
870 the results to the corresponding @var{var} variables and evaluate
873 @code{letpar} is like @code{let} (@pxref{Local Bindings}), but all the
874 expressions for the bindings are evaluated in parallel.
877 @deffn {Scheme Procedure} par-map proc lst1 @dots{} lstN
878 @deffnx {Scheme Procedure} par-for-each proc lst1 @dots{} lstN
879 Call @var{proc} on the elements of the given lists. @code{par-map}
880 returns a list comprising the return values from @var{proc}.
881 @code{par-for-each} returns an unspecified value, but waits for all
884 The @var{proc} calls are @code{(@var{proc} @var{elem1} @dots{}
885 @var{elemN})}, where each @var{elem} is from the corresponding
886 @var{lst}. Each @var{lst} must be the same length. The calls are
887 made in parallel, each in its own thread.
889 These functions are like @code{map} and @code{for-each} (@pxref{List
890 Mapping}), but make their @var{proc} calls in parallel.
893 @deffn {Scheme Procedure} n-par-map n proc lst1 @dots{} lstN
894 @deffnx {Scheme Procedure} n-par-for-each n proc lst1 @dots{} lstN
895 Call @var{proc} on the elements of the given lists, in the same way as
896 @code{par-map} and @code{par-for-each} above, but use no more than
897 @var{n} threads at any one time. The order in which calls are
898 initiated within that threads limit is unspecified.
900 These functions are good for controlling resource consumption if
901 @var{proc} calls might be costly, or if there are many to be made. On
902 a dual-CPU system for instance @math{@var{n}=4} might be enough to
903 keep the CPUs utilized, and not consume too much memory.
906 @deffn {Scheme Procedure} n-for-each-par-map n sproc pproc lst1 @dots{} lstN
907 Apply @var{pproc} to the elements of the given lists, and apply
908 @var{sproc} to each result returned by @var{pproc}. The final return
909 value is unspecified, but all calls will have been completed before
912 The calls made are @code{(@var{sproc} (@var{pproc} @var{elem1} @dots{}
913 @var{elemN}))}, where each @var{elem} is from the corresponding
914 @var{lst}. Each @var{lst} must have the same number of elements.
916 The @var{pproc} calls are made in parallel, in separate threads. No more
917 than @var{n} threads are used at any one time. The order in which
918 @var{pproc} calls are initiated within that limit is unspecified.
920 The @var{sproc} calls are made serially, in list element order, one at
921 a time. @var{pproc} calls on later elements may execute in parallel
922 with the @var{sproc} calls. Exactly which thread makes each
923 @var{sproc} call is unspecified.
925 This function is designed for individual calculations that can be done
926 in parallel, but with results needing to be handled serially, for
927 instance to write them to a file. The @var{n} limit on threads
928 controls system resource usage when there are many calculations or
929 when they might be costly.
931 It will be seen that @code{n-for-each-par-map} is like a combination
932 of @code{n-par-map} and @code{for-each},
935 (for-each sproc (n-par-map n pproc lst1 ... lstN))
939 But the actual implementation is more efficient since each @var{sproc}
940 call, in turn, can be initiated once the relevant @var{pproc} call has
941 completed, it doesn't need to wait for all to finish.
947 @c TeX-master: "guile.texi"