2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
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 @c begin (texi-doc-string "guile" "join-thread")
271 @deffn {Scheme Procedure} join-thread thread
272 Wait for @var{thread} to terminate and return its exit value. Threads
273 that have not been created with @code{call-with-new-thread} or
274 @code{scm_spawn_thread} have an exit value of @code{#f}.
277 @deffn {Scheme Procedure} thread-exited? thread
278 @deffnx {C Function} scm_thread_exited_p (thread)
279 Return @code{#t} iff @var{thread} has exited.
282 @c begin (texi-doc-string "guile" "yield")
283 @deffn {Scheme Procedure} yield
284 If one or more threads are waiting to execute, calling yield forces an
285 immediate context switch to one of them. Otherwise, yield has no effect.
288 Higher level thread procedures are available by loading the
289 @code{(ice-9 threads)} module. These provide standardized
292 @deffn macro make-thread proc [args@dots{}]
293 Apply @var{proc} to @var{args} in a new thread formed by
294 @code{call-with-new-thread} using a default error handler that display
295 the error to the current error port. The @var{args@dots{}}
296 expressions are evaluated in the new thread.
299 @deffn macro begin-thread first [rest@dots{}]
300 Evaluate forms @var{first} and @var{rest} in a new thread formed by
301 @code{call-with-new-thread} using a default error handler that display
302 the error to the current error port.
305 @node Mutexes and Condition Variables
306 @subsection Mutexes and Condition Variables
308 @cindex condition variable
310 A mutex is a thread synchronization object, it can be used by threads
311 to control access to a shared resource. A mutex can be locked to
312 indicate a resource is in use, and other threads can then block on the
313 mutex to wait for the resource (or can just test and do something else
314 if not available). ``Mutex'' is short for ``mutual exclusion''.
316 There are two types of mutexes in Guile, ``standard'' and
317 ``recursive''. They're created by @code{make-mutex} and
318 @code{make-recursive-mutex} respectively, the operation functions are
321 Note that for both types of mutex there's no protection against a
322 ``deadly embrace''. For instance if one thread has locked mutex A and
323 is waiting on mutex B, but another thread owns B and is waiting on A,
324 then an endless wait will occur (in the current implementation).
325 Acquiring requisite mutexes in a fixed order (like always A before B)
326 in all threads is one way to avoid such problems.
329 @deffn {Scheme Procedure} make-mutex
330 @deffnx {C Function} scm_make_mutex ()
331 Return a new standard mutex. It is initially unlocked.
334 @deffn {Scheme Procedure} make-recursive-mutex
335 @deffnx {C Function} scm_make_recursive_mutex ()
336 Create a new recursive mutex. It is initialloy unlocked.
339 @deffn {Scheme Procedure} lock-mutex mutex
340 @deffnx {C Function} scm_lock_mutex (mutex)
341 Lock @var{mutex}. If the mutex is already locked by another thread
342 then block and return only when @var{mutex} has been acquired.
344 For standard mutexes (@code{make-mutex}), and error is signalled if
345 the thread has itself already locked @var{mutex}.
347 For a recursive mutex (@code{make-recursive-mutex}), if the thread has
348 itself already locked @var{mutex}, then a further @code{lock-mutex}
349 call increments the lock count. An additional @code{unlock-mutex}
350 will be required to finally release.
352 When a system async (@pxref{System asyncs}) is activated for a thread
353 blocked in @code{lock-mutex}, the wait is interrupted and the async is
354 executed. When the async returns, the wait resumes.
357 @deftypefn {C Function} void scm_dynwind_lock_mutex (SCM mutex)
358 Arrange for @var{mutex} to be locked whenever the current dynwind
359 context is entered and to be unlocked when it is exited.
362 @deffn {Scheme Procedure} try-mutex mx
363 @deffnx {C Function} scm_try_mutex (mx)
364 Try to lock @var{mutex} as per @code{lock-mutex}. If @var{mutex} can
365 be acquired immediately then this is done and the return is @code{#t}.
366 If @var{mutex} is locked by some other thread then nothing is done and
367 the return is @code{#f}.
370 @deffn {Scheme Procedure} unlock-mutex mutex
371 @deffnx {C Function} scm_unlock_mutex (mutex)
372 Unlock @var{mutex}. An error is signalled if @var{mutex} is not
373 locked by the calling thread.
376 @deffn {Scheme Procedure} make-condition-variable
377 @deffnx {C Function} scm_make_condition_variable ()
378 Return a new condition variable.
381 @deffn {Scheme Procedure} wait-condition-variable condvar mutex [time]
382 @deffnx {C Function} scm_wait_condition_variable (condvar, mutex, time)
383 Wait until @var{condvar} has been signalled. While waiting,
384 @var{mutex} is atomically unlocked (as with @code{unlock-mutex}) and
385 is locked again when this function returns. When @var{time} is given,
386 it specifies a point in time where the waiting should be aborted. It
387 can be either a integer as returned by @code{current-time} or a pair
388 as returned by @code{gettimeofday}. When the waiting is aborted,
389 @code{#f} is returned. When the condition variable has in fact been
390 signalled, @code{#t} is returned. The mutex is re-locked in any case
391 before @code{wait-condition-variable} returns.
393 When a system async is activated for a thread that is blocked in a
394 call to @code{wait-condition-variable}, the waiting is interrupted,
395 the mutex is locked, and the async is executed. When the async
396 returns, the mutex is unlocked again and the waiting is resumed. When
397 the thread block while re-acquiring the mutex, execution of asyncs is
401 @deffn {Scheme Procedure} signal-condition-variable condvar
402 @deffnx {C Function} scm_signal_condition_variable (condvar)
403 Wake up one thread that is waiting for @var{condvar}.
406 @deffn {Scheme Procedure} broadcast-condition-variable condvar
407 @deffnx {C Function} scm_broadcast_condition_variable (condvar)
408 Wake up all threads that are waiting for @var{condvar}.
412 The following are higher level operations on mutexes. These are
416 (use-modules (ice-9 threads))
419 @deffn macro with-mutex mutex [body@dots{}]
420 Lock @var{mutex}, evaluate the @var{body} forms, then unlock
421 @var{mutex}. The return value is the return from the last @var{body}
424 The lock, body and unlock form the branches of a @code{dynamic-wind}
425 (@pxref{Dynamic Wind}), so @var{mutex} is automatically unlocked if an
426 error or new continuation exits @var{body}, and is re-locked if
427 @var{body} is re-entered by a captured continuation.
430 @deffn macro monitor body@dots{}
431 Evaluate the @var{body} forms, with a mutex locked so only one thread
432 can execute that code at any one time. The return value is the return
433 from the last @var{body} form.
435 Each @code{monitor} form has its own private mutex and the locking and
436 evaluation is as per @code{with-mutex} above. A standard mutex
437 (@code{make-mutex}) is used, which means @var{body} must not
438 recursively re-enter the @code{monitor} form.
440 The term ``monitor'' comes from operating system theory, where it
441 means a particular bit of code managing access to some resource and
442 which only ever executes on behalf of one process at any one time.
447 @subsection Blocking in Guile Mode
449 A thread must not block outside of a libguile function while it is in
450 guile mode. The following functions can be used to temporily leave
451 guile mode or to perform some common blocking operations in a supported
454 @deftypefn {C Function} {void *} scm_without_guile (void *(*func) (void *), void *data)
455 Leave guile mode, call @var{func} on @var{data}, enter guile mode and
456 return the result of calling @var{func}.
458 While a thread has left guile mode, it must not call any libguile
459 functions except @code{scm_with_guile} or @code{scm_without_guile} and
460 must not use any libguile macros. Also, local variables of type
461 @code{SCM} that are allocated while not in guile mode are not
462 protected from the garbage collector.
464 When used from non-guile mode, calling @code{scm_without_guile} is
465 still allowed: it simply calls @var{func}. In that way, you can leave
466 guile mode without having to know whether the current thread is in
470 @deftypefn {C Function} int scm_pthread_mutex_lock (pthread_mutex_t *mutex)
471 Like @code{pthread_mutex_lock}, but leaves guile mode while waiting for
475 @deftypefn {C Function} int scm_pthread_cond_wait (pthread_cond_t *cond, pthread_mutex_t *mutex)
476 @deftypefnx {C Function} int scm_pthread_cond_timedwait (pthread_cond_t *cond, pthread_mutex_t *mutex, struct timespec *abstime)
477 Like @code{pthread_cond_wait} and @code{pthread_cond_timedwait}, but
478 leaves guile mode while waiting for the condition variable.
481 @deftypefn {C Function} int scm_std_select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
482 Like @code{select} but leaves guile mode while waiting. Also, the
483 delivery of a system async causes this function to be interrupted with
484 error code @code{EINTR}.
487 @deftypefn {C Function} {unsigned int} scm_std_sleep ({unsigned int} seconds)
488 Like @code{sleep}, but leaves guile mode while sleeping. Also, the
489 delivery of a system async causes this function to be interrupted.
492 @deftypefn {C Function} {unsigned long} scm_std_usleep ({unsigned long} usecs)
493 Like @code{usleep}, but leaves guile mode while sleeping. Also, the
494 delivery of a system async causes this function to be interrupted.
498 @node Critical Sections
499 @subsection Critical Sections
501 @deffn {C Macro} SCM_CRITICAL_SECTION_START
502 @deffnx {C Macro} SCM_CRITICAL_SECTION_END
503 These two macros can be used to delimit a critical section.
504 Syntactically, they are both statements and need to be followed
505 immediately by a semicolon.
507 Executing @code{SCM_CRITICAL_SECTION_START} will lock a recursive
508 mutex and block the executing of system asyncs. Executing
509 @code{SCM_CRITICAL_SECTION_END} will unblock the execution of system
510 asyncs and unlock the mutex. Thus, the code that executes between
511 these two macros can only be executed in one thread at any one time
512 and no system asyncs will run. However, because the mutex is a
513 recursive one, the code might still be reentered by the same thread.
514 You must either allow for this or avoid it, both by careful coding.
516 On the other hand, critical sections delimited with these macros can
517 be nested since the mutex is recursive.
519 You must make sure that for each @code{SCM_CRITICAL_SECTION_START},
520 the corresponding @code{SCM_CRITICAL_SECTION_END} is always executed.
521 This means that no non-local exit (such as a signalled error) might
525 @deftypefn {C Function} void scm_dynwind_critical_section (SCM mutex)
526 Call @code{scm_dynwind_lock_mutex} on @var{mutex} and call
527 @code{scm_dynwind_block_asyncs}. When @var{mutex} is false, a recursive
528 mutex provided by Guile is used instead.
530 The effect of a call to @code{scm_dynwind_critical_section} is that
531 the current dynwind context (@pxref{Dynamic Wind}) turns into a
532 critical section. Because of the locked mutex, no second thread can
533 enter it concurrently and because of the blocked asyncs, no system
534 async can reenter it from the current thread.
536 When the current thread reenters the critical section anyway, the kind
537 of @var{mutex} determines what happens: When @var{mutex} is recursive,
538 the reentry is allowed. When it is a normal mutex, an error is
543 @node Fluids and Dynamic States
544 @subsection Fluids and Dynamic States
548 A @emph{fluid} is an object that can store one value per @emph{dynamic
549 state}. Each thread has a current dynamic state, and when accessing a
550 fluid, this current dynamic state is used to provide the actual value.
551 In this way, fluids can be used for thread local storage, but they are
552 in fact more flexible: dynamic states are objects of their own and can
553 be made current for more than one thread at the same time, or only be
554 made current temporarily, for example.
556 Fluids can also be used to simulate the desirable effects of
557 dynamically scoped variables. Dynamically scoped variables are useful
558 when you want to set a variable to a value during some dynamic extent
559 in the execution of your program and have them revert to their
560 original value when the control flow is outside of this dynamic
561 extent. See the description of @code{with-fluids} below for details.
563 New fluids are created with @code{make-fluid} and @code{fluid?} is
564 used for testing whether an object is actually a fluid. The values
565 stored in a fluid can be accessed with @code{fluid-ref} and
568 @deffn {Scheme Procedure} make-fluid
569 @deffnx {C Function} scm_make_fluid ()
570 Return a newly created fluid.
571 Fluids are objects that can hold one
572 value per dynamic state. That is, modifications to this value are
573 only visible to code that executes with the same dynamic state as
574 the modifying code. When a new dynamic state is constructed, it
575 inherits the values from its parent. Because each thread normally executes
576 with its own dynamic state, you can use fluids for thread local storage.
579 @deffn {Scheme Procedure} fluid? obj
580 @deffnx {C Function} scm_fluid_p (obj)
581 Return @code{#t} iff @var{obj} is a fluid; otherwise, return
585 @deffn {Scheme Procedure} fluid-ref fluid
586 @deffnx {C Function} scm_fluid_ref (fluid)
587 Return the value associated with @var{fluid} in the current
588 dynamic root. If @var{fluid} has not been set, then return
592 @deffn {Scheme Procedure} fluid-set! fluid value
593 @deffnx {C Function} scm_fluid_set_x (fluid, value)
594 Set the value associated with @var{fluid} in the current dynamic root.
597 @code{with-fluids*} temporarily changes the values of one or more fluids,
598 so that the given procedure and each procedure called by it access the
599 given values. After the procedure returns, the old values are restored.
601 @deffn {Scheme Procedure} with-fluid* fluid value thunk
602 @deffnx {C Function} scm_with_fluid (fluid, value, thunk)
603 Set @var{fluid} to @var{value} temporarily, and call @var{thunk}.
604 @var{thunk} must be a procedure with no argument.
607 @deffn {Scheme Procedure} with-fluids* fluids values thunk
608 @deffnx {C Function} scm_with_fluids (fluids, values, thunk)
609 Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
610 @var{fluids} must be a list of fluids and @var{values} must be the
611 same number of their values to be applied. Each substitution is done
612 in the order given. @var{thunk} must be a procedure with no argument.
613 it is called inside a @code{dynamic-wind} and the fluids are
614 set/restored when control enter or leaves the established dynamic
618 @deffn {Scheme Macro} with-fluids ((fluid value) ...) body...
619 Execute @var{body...} while each @var{fluid} is set to the
620 corresponding @var{value}. Both @var{fluid} and @var{value} are
621 evaluated and @var{fluid} must yield a fluid. @var{body...} is
622 executed inside a @code{dynamic-wind} and the fluids are set/restored
623 when control enter or leaves the established dynamic extent.
626 @deftypefn {C Function} SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)
627 @deftypefnx {C Function} SCM scm_c_with_fluid (SCM fluid, SCM val, SCM (*cproc)(void *), void *data)
628 The function @code{scm_c_with_fluids} is like @code{scm_with_fluids}
629 except that it takes a C function to call instead of a Scheme thunk.
631 The function @code{scm_c_with_fluid} is similar but only allows one
632 fluid to be set instead of a list.
635 @deftypefn {C Function} void scm_dynwind_fluid (SCM fluid, SCM val)
636 This function must be used inside a pair of calls to
637 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
638 Wind}). During the dynwind context, the fluid @var{fluid} is set to
641 More precisely, the value of the fluid is swapped with a `backup'
642 value whenever the dynwind context is entered or left. The backup
643 value is initialized with the @var{val} argument.
646 @deffn {Scheme Procedure} make-dynamic-state [parent]
647 @deffnx {C Function} scm_make_dynamic_state (parent)
648 Return a copy of the dynamic state object @var{parent}
649 or of the current dynamic state when @var{parent} is omitted.
652 @deffn {Scheme Procedure} dynamic-state? obj
653 @deffnx {C Function} scm_dynamic_state_p (obj)
654 Return @code{#t} if @var{obj} is a dynamic state object;
655 return @code{#f} otherwise.
658 @deftypefn {C Procedure} int scm_is_dynamic_state (SCM obj)
659 Return non-zero if @var{obj} is a dynamic state object;
660 return zero otherwise.
663 @deffn {Scheme Procedure} current-dynamic-state
664 @deffnx {C Function} scm_current_dynamic_state ()
665 Return the current dynamic state object.
668 @deffn {Scheme Procedure} set-current-dynamic-state state
669 @deffnx {C Function} scm_set_current_dynamic_state (state)
670 Set the current dynamic state object to @var{state}
671 and return the previous current dynamic state object.
674 @deffn {Scheme Procedure} with-dynamic-state state proc
675 @deffnx {C Function} scm_with_dynamic_state (state, proc)
676 Call @var{proc} while @var{state} is the current dynamic
680 @deftypefn {C Procedure} void scm_dynwind_current_dynamic_state (SCM state)
681 Set the current dynamic state to @var{state} for the current dynwind
685 @deftypefn {C Procedure} {void *} scm_c_with_dynamic_state (SCM state, void *(*func)(void *), void *data)
686 Like @code{scm_with_dynamic_state}, but call @var{func} with
691 @c @subsection Futures
694 @c -- Futures are disabled for the time being, see futures.h for an
697 @c Futures are a convenient way to run a calculation in a new thread, and
698 @c only wait for the result when it's actually needed.
700 @c Futures are similar to promises (@pxref{Delayed Evaluation}), in that
701 @c they allow mainline code to continue immediately. But @code{delay}
702 @c doesn't evaluate at all until forced, whereas @code{future} starts
703 @c immediately in a new thread.
705 @c @deffn {syntax} future expr
706 @c Begin evaluating @var{expr} in a new thread, and return a ``future''
707 @c object representing the calculation.
710 @c @deffn {Scheme Procedure} make-future thunk
711 @c @deffnx {C Function} scm_make_future (thunk)
712 @c Begin evaluating the call @code{(@var{thunk})} in a new thread, and
713 @c return a ``future'' object representing the calculation.
716 @c @deffn {Scheme Procedure} future-ref f
717 @c @deffnx {C Function} scm_future_ref (f)
718 @c Return the value computed by the future @var{f}. If @var{f} has not
719 @c yet finished executing then wait for it to do so.
724 @subsection Parallel forms
725 @cindex parallel forms
727 The functions described in this section are available from
730 (use-modules (ice-9 threads))
733 @deffn syntax parallel expr1 @dots{} exprN
734 Evaluate each @var{expr} expression in parallel, each in its own thread.
735 Return the results as a set of @var{N} multiple values
736 (@pxref{Multiple Values}).
739 @deffn syntax letpar ((var1 expr1) @dots{} (varN exprN)) body@dots{}
740 Evaluate each @var{expr} in parallel, each in its own thread, then bind
741 the results to the corresponding @var{var} variables and evaluate
744 @code{letpar} is like @code{let} (@pxref{Local Bindings}), but all the
745 expressions for the bindings are evaluated in parallel.
748 @deffn {Scheme Procedure} par-map proc lst1 @dots{} lstN
749 @deffnx {Scheme Procedure} par-for-each proc lst1 @dots{} lstN
750 Call @var{proc} on the elements of the given lists. @code{par-map}
751 returns a list comprising the return values from @var{proc}.
752 @code{par-for-each} returns an unspecified value, but waits for all
755 The @var{proc} calls are @code{(@var{proc} @var{elem1} @dots{}
756 @var{elemN})}, where each @var{elem} is from the corresponding
757 @var{lst}. Each @var{lst} must be the same length. The calls are
758 made in parallel, each in its own thread.
760 These functions are like @code{map} and @code{for-each} (@pxref{List
761 Mapping}), but make their @var{proc} calls in parallel.
764 @deffn {Scheme Procedure} n-par-map n proc lst1 @dots{} lstN
765 @deffnx {Scheme Procedure} n-par-for-each n proc lst1 @dots{} lstN
766 Call @var{proc} on the elements of the given lists, in the same way as
767 @code{par-map} and @code{par-for-each} above, but use no more than
768 @var{n} threads at any one time. The order in which calls are
769 initiated within that threads limit is unspecified.
771 These functions are good for controlling resource consumption if
772 @var{proc} calls might be costly, or if there are many to be made. On
773 a dual-CPU system for instance @math{@var{n}=4} might be enough to
774 keep the CPUs utilized, and not consume too much memory.
777 @deffn {Scheme Procedure} n-for-each-par-map n sproc pproc lst1 @dots{} lstN
778 Apply @var{pproc} to the elements of the given lists, and apply
779 @var{sproc} to each result returned by @var{pproc}. The final return
780 value is unspecified, but all calls will have been completed before
783 The calls made are @code{(@var{sproc} (@var{pproc} @var{elem1} @dots{}
784 @var{elemN}))}, where each @var{elem} is from the corresponding
785 @var{lst}. Each @var{lst} must have the same number of elements.
787 The @var{pproc} calls are made in parallel, in separate threads. No more
788 than @var{n} threads are used at any one time. The order in which
789 @var{pproc} calls are initiated within that limit is unspecified.
791 The @var{sproc} calls are made serially, in list element order, one at
792 a time. @var{pproc} calls on later elements may execute in parallel
793 with the @var{sproc} calls. Exactly which thread makes each
794 @var{sproc} call is unspecified.
796 This function is designed for individual calculations that can be done
797 in parallel, but with results needing to be handled serially, for
798 instance to write them to a file. The @var{n} limit on threads
799 controls system resource usage when there are many calculations or
800 when they might be costly.
802 It will be seen that @code{n-for-each-par-map} is like a combination
803 of @code{n-par-map} and @code{for-each},
806 (for-each sproc (n-par-map n pproc lst1 ... lstN))
810 But the actual implementation is more efficient since each @var{sproc}
811 call, in turn, can be initiated once the relevant @var{pproc} call has
812 completed, it doesn't need to wait for all to finish.
818 @c TeX-master: "guile.texi"