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 * Dynamic Roots:: Root frames of execution.
19 * Threads:: Multiple threads of execution.
20 * Fluids:: Thread-local variables.
21 * Futures:: Delayed execution in new threads.
22 * Parallel Forms:: Parallel execution of forms.
23 * Mutexes:: Synchronization primitives.
31 Arbiters are synchronization objects, they can be used by threads to
32 control access to a shared resource. An arbiter can be locked to
33 indicate a resource is in use, and unlocked when done.
35 An arbiter is like a light-weight mutex (@pxref{Mutexes}). It uses
36 less memory and may be faster, but there's no way for a thread to
37 block waiting on an arbiter, it can only test and get the status
40 @deffn {Scheme Procedure} make-arbiter name
41 @deffnx {C Function} scm_make_arbiter (name)
42 Return an object of type arbiter and name @var{name}. Its
43 state is initially unlocked. Arbiters are a way to achieve
44 process synchronization.
47 @deffn {Scheme Procedure} try-arbiter arb
48 @deffnx {C Function} scm_try_arbiter (arb)
49 @deffnx {C Function} scm_try_arbiter (arb)
50 If @var{arb} is unlocked, then lock it and return @code{#t}.
51 If @var{arb} is already locked, then do nothing and return
55 @deffn {Scheme Procedure} release-arbiter arb
56 @deffnx {C Function} scm_release_arbiter (arb)
57 If @var{arb} is locked, then unlock it and return @code{#t}. If
58 @var{arb} is already unlocked, then do nothing and return @code{#f}.
60 Typical usage is for the thread which locked an arbiter to later
61 release it, but that's not required, any thread can release it.
72 Asyncs are a means of deferring the excution of Scheme code until it is
75 Guile provides two kinds of asyncs that share the basic concept but are
76 otherwise quite different: system asyncs and user asyncs. System asyncs
77 are integrated into the core of Guile and are executed automatically
78 when the system is in a state to allow the execution of Scheme code.
79 For example, it is not possible to execute Scheme code in a POSIX signal
80 handler, but such a signal handler can queue a system async to be
81 executed in the near future, when it is safe to do so.
83 System asyncs can also be queued for threads other than the current one.
84 This way, you can cause threads to asynchronously execute arbitrary
87 User asyncs offer a convenient means of queueing procedures for future
88 execution and triggering this execution. They will not be executed
97 @subsubsection System asyncs
99 To cause the future asynchronous execution of a procedure in a given
100 thread, use @code{system-async-mark}.
102 Automatic invocation of system asyncs can be temporarily disabled by
103 calling @code{call-with-blocked-asyncs}. This function works by
104 temporarily increasing the @emph{async blocking level} of the current
105 thread while a given procedure is running. The blocking level starts
106 out at zero, and whenever a safe point is reached, a blocking level
107 greater than zero will prevent the execution of queued asyncs.
109 Analogously, the procedure @code{call-with-unblocked-asyncs} will
110 temporarily decrease the blocking level of the current thread. You
111 can use it when you want to disable asyncs by default and only allow
114 In addition to the C versions of @code{call-with-blocked-asyncs} and
115 @code{call-with-unblocked-asyncs}, C code can use
116 @code{scm_with_blocked_asyncs} and @code{scm_with_unblocked_asyncs}
117 inside a @dfn{frame} (@pxref{Frames}) to block or unblock system asyncs
120 @deffn {Scheme Procedure} system-async-mark proc [thread]
121 @deffnx {C Function} scm_system_async_mark (proc)
122 @deffnx {C Function} scm_system_async_mark_for_thread (proc, thread)
123 Mark @var{proc} (a procedure with zero arguments) for future execution
124 in @var{thread}. When @var{proc} has already been marked for
125 @var{thread} but has not been executed yet, this call has no effect.
126 When @var{thread} is omitted, the thread that called
127 @code{system-async-mark} is used.
129 This procedure is not safe to be called from signal handlers. Use
130 @code{scm_sigaction} or @code{scm_sigaction_for_thread} to install
134 @c FIXME: The use of @deffnx for scm_c_call_with_blocked_asyncs and
135 @c scm_c_call_with_unblocked_asyncs puts "void" into the function
136 @c index. Would prefer to use @deftypefnx if makeinfo allowed that,
137 @c or a @deftypefn with an empty return type argument if it didn't
138 @c introduce an extra space.
140 @deffn {Scheme Procedure} call-with-blocked-asyncs proc
141 @deffnx {C Function} scm_call_with_blocked_asyncs (proc)
142 @deffnx {C Function} void *scm_c_call_with_blocked_asyncs (void * (*proc) (void *data), void *data)
143 @findex scm_c_call_with_blocked_asyncs
144 Call @var{proc} and block the execution of system asyncs by one level
145 for the current thread while it is running. Return the value returned
146 by @var{proc}. For the first two variants, call @var{proc} with no
147 arguments; for the third, call it with @var{data}.
150 @deffn {Scheme Procedure} call-with-unblocked-asyncs proc
151 @deffnx {C Function} scm_call_with_unblocked_asyncs (proc)
152 @deffnx {C Function} void *scm_c_call_with_unblocked_asyncs (void *(*p) (void *d), void *d)
153 @findex scm_c_call_with_unblocked_asyncs
154 Call @var{proc} and unblock the execution of system asyncs by one
155 level for the current thread while it is running. Return the value
156 returned by @var{proc}. For the first two variants, call @var{proc}
157 with no arguments; for the third, call it with @var{data}.
160 @deftypefn {C Function} void scm_frame_block_asyncs ()
161 This function must be used inside a pair of calls to
162 @code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
163 During the dynamic extent of the frame, asyncs are blocked by one level.
166 @deftypefn {C Function} void scm_frame_unblock_asyncs ()
167 This function must be used inside a pair of calls to
168 @code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
169 During the dynamic extent of the frame, asyncs are unblocked by one
174 @subsubsection User asyncs
176 A user async is a pair of a thunk (a parameterless procedure) and a
177 mark. Setting the mark on a user async will cause the thunk to be
178 executed when the user async is passed to @code{run-asyncs}. Setting
179 the mark more than once is satisfied by one execution of the thunk.
181 User asyncs are created with @code{async}. They are marked with
184 @deffn {Scheme Procedure} async thunk
185 @deffnx {C Function} scm_async (thunk)
186 Create a new user async for the procedure @var{thunk}.
189 @deffn {Scheme Procedure} async-mark a
190 @deffnx {C Function} scm_async_mark (a)
191 Mark the user async @var{a} for future execution.
194 @deffn {Scheme Procedure} run-asyncs list_of_a
195 @deffnx {C Function} scm_run_asyncs (list_of_a)
196 Execute all thunks from the marked asyncs of the list @var{list_of_a}.
201 @subsection Dynamic Roots
202 @cindex dynamic roots
204 A @dfn{dynamic root} is a root frame of Scheme evaluation.
205 The top-level repl, for example, is an instance of a dynamic root.
207 Each dynamic root has its own chain of dynamic-wind information. Each
208 has its own set of continuations, jump-buffers, and pending CATCH
209 statements which are inaccessible from the dynamic scope of any
212 In a thread-based system, each thread has its own dynamic root. Therefore,
213 continuations created by one thread may not be invoked by another.
215 Even in a single-threaded system, it is sometimes useful to create a new
216 dynamic root. For example, if you want to apply a procedure, but to
217 not allow that procedure to capture the current continuation, calling
218 the procedure under a new dynamic root will do the job.
220 @deffn {Scheme Procedure} call-with-dynamic-root thunk handler
221 @deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
222 Evaluate @code{(thunk)} in a new dynamic context, returning its value.
224 If an error occurs during evaluation, apply @var{handler} to the
225 arguments to the throw, just as @code{throw} would. If this happens,
226 @var{handler} is called outside the scope of the new root -- it is
227 called in the same dynamic context in which
228 @code{call-with-dynamic-root} was evaluated.
230 If @var{thunk} captures a continuation, the continuation is rooted at
231 the call to @var{thunk}. In particular, the call to
232 @code{call-with-dynamic-root} is not captured. Therefore,
233 @code{call-with-dynamic-root} always returns at most one time.
235 Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
236 the root and a new chain started for @var{thunk}. Therefore, this call
237 may not do what you expect:
240 ;; Almost certainly a bug:
245 (call-with-dynamic-root
249 (lambda (errcode) errcode))))
252 The problem is, on what port will @samp{fnord} be displayed? You
253 might expect that because of the @code{with-output-to-port} that
254 it will be displayed on the port bound to @code{some-port}. But it
255 probably won't -- before evaluating the thunk, dynamic winds are
256 unwound, including those created by @code{with-output-to-port}.
257 So, the standard output port will have been re-set to its default value
258 before @code{display} is evaluated.
260 (This function was added to Guile mostly to help calls to functions in C
261 libraries that can not tolerate non-local exits or calls that return
262 multiple times. If such functions call back to the interpreter, it should
263 be under a new dynamic root.)
267 @deffn {Scheme Procedure} dynamic-root
268 @deffnx {C Function} scm_dynamic_root ()
269 Return an object representing the current dynamic root.
271 These objects are only useful for comparison using @code{eq?}.
272 They are currently represented as numbers, but your code should
273 in no way depend on this.
276 @c begin (scm-doc-string "boot-9.scm" "quit")
277 @deffn {Scheme Procedure} quit [exit_val]
278 Throw back to the error handler of the current dynamic root.
280 If integer @var{exit_val} is specified and if Guile is being used
281 stand-alone and if quit is called from the initial dynamic-root,
282 @var{exit_val} becomes the exit status of the Guile process and the
286 When Guile is run interactively, errors are caught from within the
287 read-eval-print loop. An error message will be printed and @code{abort}
288 called. A default set of signal handlers is installed, e.g., to allow
289 user interrupt of the interpreter.
291 It is possible to switch to a "batch mode", in which the interpreter
292 will terminate after an error and in which all signals cause their
293 default actions. Switching to batch mode causes any handlers installed
294 from Scheme code to be removed. An example of where this is useful is
295 after forking a new process intended to run non-interactively.
297 @c begin (scm-doc-string "boot-9.scm" "batch-mode?")
298 @deffn {Scheme Procedure} batch-mode?
299 Returns a boolean indicating whether the interpreter is in batch mode.
302 @c begin (scm-doc-string "boot-9.scm" "set-batch-mode?!")
303 @deffn {Scheme Procedure} set-batch-mode?! arg
304 If @var{arg} is true, switches the interpreter to batch mode.
305 The @code{#f} case has not been implemented.
311 @cindex Guile threads
312 @cindex POSIX threads
314 Guile threads are implemented using POSIX threads, they run
315 pre-emptively and concurrently through both Scheme code and system
316 calls. The only exception is for garbage collection, where all
317 threads must rendezvous.
320 * Low level thread primitives::
321 * Higher level thread procedures::
322 * C level thread interface::
326 @node Low level thread primitives
327 @subsubsection Low level thread primitives
329 @deffn {Scheme Procedure} all-threads
330 @deffnx {C Function} scm_all_threads ()
331 Return a list of all threads.
334 @deffn {Scheme Procedure} current-thread
335 @deffnx {C Function} scm_current_thread ()
336 Return the thread that called this function.
339 @c begin (texi-doc-string "guile" "call-with-new-thread")
340 @deffn {Scheme Procedure} call-with-new-thread thunk error-handler
341 Evaluate @code{(thunk)} in a new thread, and new dynamic context,
342 returning a new thread object representing the thread.
344 If an error occurs during evaluation, call error-handler, passing it
345 an error code. If this happens, the error-handler is called outside
346 the scope of the new root -- it is called in the same dynamic context
347 in which with-new-thread was evaluated, but not in the caller's
350 All the evaluation rules for dynamic roots apply to threads.
353 @c begin (texi-doc-string "guile" "join-thread")
354 @deffn {Scheme Procedure} join-thread thread
355 Suspend execution of the calling thread until the target @var{thread}
356 terminates, unless the target @var{thread} has already terminated.
359 @deffn {Scheme Procedure} thread-exited? thread
360 @deffnx {C Function} scm_thread_exited_p (thread)
361 Return @code{#t} iff @var{thread} has exited.
364 @c begin (texi-doc-string "guile" "yield")
365 @deffn {Scheme Procedure} yield
366 If one or more threads are waiting to execute, calling yield forces an
367 immediate context switch to one of them. Otherwise, yield has no effect.
370 @c begin (texi-doc-string "guile" "make-condition-variable")
371 @deffn {Scheme Procedure} make-condition-variable
372 Make a new condition variable.
375 @deffn {Scheme Procedure} make-fair-condition-variable
376 @deffnx {C Function} scm_make_fair_condition_variable ()
377 Make a new fair condition variable.
380 @c begin (texi-doc-string "guile" "wait-condition-variable")
381 @deffn {Scheme Procedure} wait-condition-variable cond-var mutex [time]
382 Wait until @var{cond-var} has been signalled. While waiting,
383 @var{mutex} is atomically unlocked (as with @code{unlock-mutex}) and
384 is locked again when this function returns. When @var{time} is given,
385 it specifies a point in time where the waiting should be aborted. It
386 can be either a integer as returned by @code{current-time} or a pair
387 as returned by @code{gettimeofday}. When the waiting is aborted,
388 @code{#f} is returned. When the condition variable has in fact been
389 signalled, @code{#t} is returned. The mutex is re-locked in any case
390 before @code{wait-condition-variable} returns.
392 When a system async is activated for a thread that is blocked in a
393 call to @code{wait-condition-variable}, the waiting is interrupted,
394 the mutex is locked, and the async is executed. When the async
395 returns, the mutex is unlocked again and the waiting is resumed.
398 @c begin (texi-doc-string "guile" "signal-condition-variable")
399 @deffn {Scheme Procedure} signal-condition-variable cond-var
400 Wake up one thread that is waiting for @var{cv}.
403 @c begin (texi-doc-string "guile" "broadcast-condition-variable")
404 @deffn {Scheme Procedure} broadcast-condition-variable cond-var
405 Wake up all threads that are waiting for @var{cv}.
408 @node Higher level thread procedures
409 @subsubsection Higher level thread procedures
411 @c new by ttn, needs review
413 Higher level thread procedures are available by loading the
414 @code{(ice-9 threads)} module. These provide standardized
417 @deffn macro make-thread proc [args@dots{}]
418 Apply @var{proc} to @var{args} in a new thread formed by
419 @code{call-with-new-thread} using a default error handler that display
420 the error to the current error port.
423 @deffn macro begin-thread first [rest@dots{}]
424 Evaluate forms @var{first} and @var{rest} in a new thread formed by
425 @code{call-with-new-thread} using a default error handler that display
426 the error to the current error port.
429 @node C level thread interface
430 @subsubsection C level thread interface
432 You can create and manage threads
433 with the C versions of the primitives above.
435 functions and data types are only available from C and can not be
436 mixed with the first set from above. However, they might be more
437 efficient and can be used in situations where Scheme data types are
438 not allowed or are inconvenient to use.
440 Furthermore, they are the primitives that Guile relies on for its own
441 higher level threads. By reimplementing them, you can adapt Guile to
442 different low-level thread implementations.
444 C code in a thread must call a libguile function periodically. When
445 one thread finds garbage collection is required, it waits for all
446 threads to rendezvous before doing that GC. Such a rendezvous is
447 checked within libguile functions. If C code wants to sleep or block
448 in a thread it should use one of the libguile functions provided.
450 Only threads created by Guile can use the libguile functions. Threads
451 created directly with say @code{pthread_create} are unknown to Guile
452 and they cannot call libguile. The stack in such foreign threads is
453 not scanned during GC, so @code{SCM} values generally cannot be held
458 @c Describe SCM_TICK which can be called if no other libguile
459 @c function is being used by a C function.
461 @c Describe "Guile mode", which a thread can enter and exit. There
462 @c are no functions for doing this yet.
464 @c When in guile mode a thread can call libguile, is subject to the
465 @c tick rule, and its stack is scanned. When not in guile mode it
466 @c cannot call libguile, it doesn't have to tick, and its stack is
467 @c not scanned. The strange guile control flow things like
468 @c exceptions, continuations and asyncs only occur when in guile
471 @c When guile mode is exited, the portion of the stack allocated
472 @c while it was in guile mode is still scanned. This portion may not
473 @c be modified when outside guile mode. The stack ends up
474 @c partitioned into alternating guile and non-guile regions.
476 @c Leaving guile mode is convenient when running an extended
477 @c calculation not involving guile, since one doesn't need to worry
478 @c about SCM_TICK calls.
481 @deftp {C Data Type} scm_t_thread
482 This data type represents a thread, to be used with scm_thread_create,
486 @deftypefn {C Function} int scm_thread_create (scm_t_thread *t, void (*proc)(void *), void *data)
487 Create a new thread that will start by calling @var{proc}, passing it
488 @var{data}. A handle for the new thread is stored in @var{t}, which
489 must be non-NULL. The thread terminated when @var{proc} returns.
490 When the thread has not been detached, its handle remains valid after
491 is has terminated so that it can be used with @var{scm_thread_join},
492 for example. When it has been detached, the handle becomes invalid as
493 soon as the thread terminates.
496 @deftypefn {C Function} void scm_thread_detach (scm_t_thread t)
497 Detach the thread @var{t}. See @code{scm_thread_create}.
500 @deftypefn {C Function} void scm_thread_join (scm_t_thread t)
501 Wait for thread @var{t} to terminate. The thread must not have been
502 detached at the time that @code{scm_thread_join} is called, but it
503 might have been detached by the time it terminates.
506 @deftypefn {C Function} scm_t_thread scm_thread_self ()
507 Return the handle of the calling thread.
510 @deftp {C Data Type} scm_t_cond
511 This data type represents a condition variable, to be used with
515 @deftypefn {C Function} void scm_cond_init (scm_t_cond *c)
516 Initialize the condition variable structure pointed to by @var{c}.
519 @deftypefn {C Function} void scm_cond_destroy (scm_t_cond *c)
520 Deallocate all resources associated with @var{c}.
523 @deftypefn {C Function} void scm_cond_wait (scm_t_cond *c, scm_t_mutex *m)
524 Wait for @var{c} to be signalled. While waiting @var{m} is unlocked
525 and locked again before @code{scm_cond_wait} returns.
528 @deftypefn {C Function} void scm_cond_timedwait (scm_t_cond *c, scm_t_mutex *m, timespec *abstime)
529 Wait for @var{c} to be signalled as with @code{scm_cond_wait} but
530 don't wait longer than the point in time specified by @var{abstime}.
531 when the waiting is aborted, zero is returned; non-zero else.
534 @deftypefn {C Function} void scm_cond_signal (scm_t_cond *c)
535 Signal the condition variable @var{c}. When one or more threads are
536 waiting for it to be signalled, select one arbitrarily and let its
540 @deftypefn {C Function} void scm_cond_broadcast (scm_t_cond *c)
541 Signal the condition variable @var{c}. When there are threads waiting
542 for it to be signalled, wake them all up and make all their waits
546 @deftp {C Type} scm_t_key
547 This type represents a key for a thread-specific value.
550 @deftypefn {C Function} void scm_key_create (scm_t_key *keyp)
551 Create a new key for a thread-specific value. Each thread has its own
552 value associated to such a handle. The new handle is stored into
553 @var{keyp}, which must be non-NULL.
556 @deftypefn {C Function} void scm_key_delete (scm_t_key key)
557 This function makes @var{key} invalid as a key for thread-specific data.
560 @deftypefn {C Function} void scm_key_setspecific (scm_t_key key, const void *value)
561 Associate @var{value} with @var{key} in the calling thread.
564 @deftypefn {C Function} int scm_key_getspecific (scm_t_key key)
565 Return the value currently associated with @var{key} in the calling
566 thread. When @code{scm_key_setspecific} has not yet been called in
567 this thread with this key, @code{NULL} is returned.
570 @deftypefn {C Function} int scm_thread_select (...)
571 This function does the same thing as the system's @code{select}
572 function, but in a way that is friendly to the thread implementation.
573 You should call it in preference to the system @code{select}.
581 Fluids are objects to store values in. They have a few properties
582 which make them useful in certain situations: Fluids can have one
583 value per dynamic root (@pxref{Dynamic Roots}), so that changes to the
584 value in a fluid are only visible in the same dynamic root. Since
585 threads are executed in separate dynamic roots, fluids can be used for
586 thread local storage (@pxref{Threads}).
588 Fluids can be used to simulate the desirable effects of dynamically
589 scoped variables. Dynamically scoped variables are useful when you
590 want to set a variable to a value during some dynamic extent in the
591 execution of your program and have them revert to their original value
592 when the control flow is outside of this dynamic extent. See the
593 description of @code{with-fluids} below for details.
595 New fluids are created with @code{make-fluid} and @code{fluid?} is
596 used for testing whether an object is actually a fluid. The values
597 stored in a fluid can be accessed with @code{fluid-ref} and
600 @deffn {Scheme Procedure} make-fluid
601 @deffnx {C Function} scm_make_fluid ()
602 Return a newly created fluid.
603 Fluids are objects of a certain type (a smob) that can hold one SCM
604 value per dynamic root. That is, modifications to this value are
605 only visible to code that executes within the same dynamic root as
606 the modifying code. When a new dynamic root is constructed, it
607 inherits the values from its parent. Because each thread executes
608 in its own dynamic root, you can use fluids for thread local storage.
611 @deffn {Scheme Procedure} fluid? obj
612 @deffnx {C Function} scm_fluid_p (obj)
613 Return @code{#t} iff @var{obj} is a fluid; otherwise, return
617 @deffn {Scheme Procedure} fluid-ref fluid
618 @deffnx {C Function} scm_fluid_ref (fluid)
619 Return the value associated with @var{fluid} in the current
620 dynamic root. If @var{fluid} has not been set, then return
624 @deffn {Scheme Procedure} fluid-set! fluid value
625 @deffnx {C Function} scm_fluid_set_x (fluid, value)
626 Set the value associated with @var{fluid} in the current dynamic root.
629 @code{with-fluids*} temporarily changes the values of one or more fluids,
630 so that the given procedure and each procedure called by it access the
631 given values. After the procedure returns, the old values are restored.
633 @deffn {Scheme Procedure} with-fluid* fluid value thunk
634 @deffnx {C Function} scm_with_fluid (fluid, value, thunk)
635 Set @var{fluid} to @var{value} temporarily, and call @var{thunk}.
636 @var{thunk} must be a procedure with no argument.
639 @deffn {Scheme Procedure} with-fluids* fluids values thunk
640 @deffnx {C Function} scm_with_fluids (fluids, values, thunk)
641 Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
642 @var{fluids} must be a list of fluids and @var{values} must be the
643 same number of their values to be applied. Each substitution is done
644 in the order given. @var{thunk} must be a procedure with no argument.
645 it is called inside a @code{dynamic-wind} and the fluids are
646 set/restored when control enter or leaves the established dynamic
650 @deffn {Scheme Macro} with-fluids ((fluid value) ...) body...
651 Execute @var{body...} while each @var{fluid} is set to the
652 corresponding @var{value}. Both @var{fluid} and @var{value} are
653 evaluated and @var{fluid} must yield a fluid. @var{body...} is
654 executed inside a @code{dynamic-wind} and the fluids are set/restored
655 when control enter or leaves the established dynamic extent.
658 @deftypefn {C Function} SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)
659 @deftypefnx {C Function} SCM scm_c_with_fluid (SCM fluid, SCM val, SCM (*cproc)(void *), void *data)
660 The function @code{scm_c_with_fluids} is like @code{scm_with_fluids}
661 except that it takes a C function to call instead of a Scheme thunk.
663 The function @code{scm_c_with_fluid} is similar but only allows one
664 fluid to be set instead of a list.
667 @deftypefn {C Function} void scm_frame_fluid (SCM fluid, SCM val)
668 This function must be used inside a pair of calls to
669 @code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
670 During the dynamic extent of the frame, the fluid @var{fluid} is set
673 More precisely, the value of the fluid is swapped with a `backup'
674 value whenever the frame is entered or left. The backup value is
675 initialized with the @var{val} argument.
682 Futures are a convenient way to run a calculation in a new thread, and
683 only wait for the result when it's actually needed.
685 Futures are similar to promises (@pxref{Delayed Evaluation}), in that
686 they allow mainline code to continue immediately. But @code{delay}
687 doesn't evaluate at all until forced, whereas @code{future} starts
688 immediately in a new thread.
690 @deffn {syntax} future expr
691 Begin evaluating @var{expr} in a new thread, and return a ``future''
692 object representing the calculation.
695 @deffn {Scheme Procedure} make-future thunk
696 @deffnx {C Function} scm_make_future (thunk)
697 Begin evaluating the call @code{(@var{thunk})} in a new thread, and
698 return a ``future'' object representing the calculation.
701 @deffn {Scheme Procedure} future-ref f
702 @deffnx {C Function} scm_future_ref (f)
703 Return the value computed by the future @var{f}. If @var{f} has not
704 yet finished executing then wait for it to do so.
709 @subsection Parallel forms
710 @cindex parallel forms
712 The functions described in this section are available from
715 (use-modules (ice-9 threads))
718 @deffn syntax parallel expr1 @dots{} exprN
719 Evaluate each @var{expr} expression in parallel, each in its own thread.
720 Return the results as a set of @var{N} multiple values
721 (@pxref{Multiple Values}).
724 @deffn syntax letpar ((var1 expr1) @dots{} (varN exprN)) body@dots{}
725 Evaluate each @var{expr} in parallel, each in its own thread, then bind
726 the results to the corresponding @var{var} variables and evaluate
729 @code{letpar} is like @code{let} (@pxref{Local Bindings}), but all the
730 expressions for the bindings are evaluated in parallel.
733 @deffn {Scheme Procedure} par-map proc lst1 @dots{} lstN
734 @deffnx {Scheme Procedure} par-for-each proc lst1 @dots{} lstN
735 Call @var{proc} on the elements of the given lists. @code{par-map}
736 returns a list comprising the return values from @var{proc}.
737 @code{par-for-each} returns an unspecified value, but waits for all
740 The @var{proc} calls are @code{(@var{proc} @var{elem1} @dots{}
741 @var{elemN})}, where each @var{elem} is from the corresponding
742 @var{lst}. Each @var{lst} must be the same length. The calls are
743 made in parallel, each in its own thread.
745 These functions are like @code{map} and @code{for-each} (@pxref{List
746 Mapping}), but make their @var{proc} calls in parallel.
749 @deffn {Scheme Procedure} n-par-map n proc lst1 @dots{} lstN
750 @deffnx {Scheme Procedure} n-par-for-each n proc lst1 @dots{} lstN
751 Call @var{proc} on the elements of the given lists, in the same way as
752 @code{par-map} and @code{par-for-each} above, but use no more than
753 @var{n} threads at any one time. The order in which calls are
754 initiated within that threads limit is unspecified.
756 These functions are good for controlling resource consumption if
757 @var{proc} calls might be costly, or if there are many to be made. On
758 a dual-CPU system for instance @math{@var{n}=4} might be enough to
759 keep the CPUs utilized, and not consume too much memory.
762 @deffn {Scheme Procedure} n-for-each-par-map n sproc pproc lst1 @dots{} lstN
763 Apply @var{pproc} to the elements of the given lists, and apply
764 @var{sproc} to each result returned by @var{pproc}. The final return
765 value is unspecified, but all calls will have been completed before
768 The calls made are @code{(@var{sproc} (@var{pproc} @var{elem1} @dots{}
769 @var{elemN}))}, where each @var{elem} is from the corresponding
770 @var{lst}. Each @var{lst} must have the same number of elements.
772 The @var{pproc} calls are made in parallel, in separate threads. No more
773 than @var{n} threads are used at any one time. The order in which
774 @var{pproc} calls are initiated within that limit is unspecified.
776 The @var{sproc} calls are made serially, in list element order, one at
777 a time. @var{pproc} calls on later elements may execute in parallel
778 with the @var{sproc} calls. Exactly which thread makes each
779 @var{sproc} call is unspecified.
781 This function is designed for individual calculations that can be done
782 in parallel, but with results needing to be handled serially, for
783 instance to write them to a file. The @var{n} limit on threads
784 controls system resource usage when there are many calculations or
785 when they might be costly.
787 It will be seen that @code{n-for-each-par-map} is like a combination
788 of @code{n-par-map} and @code{for-each},
791 (for-each sproc (n-par-map n pproc lst1 ... lstN))
795 But the actual implementation is more efficient since each @var{sproc}
796 call, in turn, can be initiated once the relevant @var{pproc} call has
797 completed, it doesn't need to wait for all to finish.
805 A mutex is a thread synchronization object, it can be used by threads
806 to control access to a shared resource. A mutex can be locked to
807 indicate a resource is in use, and other threads can then block on the
808 mutex to wait for the resource (or can just test and do something else
809 if not available). ``Mutex'' is short for ``mutual exclusion''.
811 There are two types of mutexes, ``standard'' and ``fair''. They're
812 created by @code{make-mutex} and @code{make-fair-mutex} respectively,
813 the operation functions are then common to both.
815 Note that for both types of mutex there's no protection against a
816 ``deadly embrace''. For instance if one thread has locked mutex A and
817 is waiting on mutex B, but another thread owns B and is waiting on A,
818 then an endless wait will occur (in the current implementation).
819 Acquiring requisite mutexes in a fixed order (like always A before B)
820 in all threads is one way to avoid such problems.
823 @deffn {Scheme Procedure} make-mutex
824 @deffnx {Scheme Procedure} make-fair-mutex
825 Return a new mutex object.
827 @code{make-mutex} creates a standard mutex. This is fast, but its
828 features are restricted. Recursive locking (multiple lock calls by
829 one thread) is not permitted, and an unlock can be done only when
830 already locked and only by the owning thread. When multiple threads
831 are blocked waiting to acquire the mutex, it's unspecified which will
834 @code{make-fair-mutex} creates a fair mutex. This has more features
835 and error checking. Recursive locking is allowed, a given thread can
836 make multiple lock calls and the mutex is released when a balancing
837 number of unlocks are done. Other threads blocked waiting to acquire
838 the mutex form a queue and the one waiting longest will be the next to
842 @deffn {Scheme Procedure} lock-mutex mutex
843 Lock @var{mutex}. If the mutex is already locked by another thread
844 then block and return only when @var{mutex} has been acquired.
846 For standard mutexes (@code{make-mutex}), if the thread has itself
847 already locked @var{mutex} it must not call @code{lock-mutex} on it a
848 further time. Behaviour is unspecified if this is done.
850 For a fair mutex (@code{make-fair-mutex}), if the thread has itself
851 already locked @var{mutex}, then a further @code{lock-mutex} call
852 increments the lock count. An additional @code{unlock-mutex} will be
853 required to finally release.
855 When a system async (@pxref{System asyncs}) is activated for a thread
856 blocked in @code{lock-mutex}, the wait is interrupted and the async is
857 executed. When the async returns the wait resumes.
860 @deffn {Scheme Procedure} try-mutex mutex
861 Try to lock @var{mutex} as per @code{lock-mutex}. If @var{mutex} can
862 be acquired immediately then this is done and the return is @code{#t}.
863 If @var{mutex} is locked by some other thread then nothing is done and
864 the return is @code{#f}.
867 @deffn {Scheme Procedure} unlock-mutex mutex
870 For a standard mutex (@code{make-mutex}), if @var{mutex} is not locked
871 by the calling thread then behaviour is unspecified.
873 For a fair mutex (@code{make-fair-mutex}), if @var{mutex} is not
874 locked by the calling thread then an error is thrown.
878 The following are higher level operations on mutexes. These are
882 (use-modules (ice-9 threads))
885 @deffn macro with-mutex mutex [body@dots{}]
886 Lock @var{mutex}, evaluate the @var{body} forms, then unlock
887 @var{mutex}. The return value is the return from the last @var{body}
890 The lock, body and unlock form the branches of a @code{dynamic-wind}
891 (@pxref{Dynamic Wind}), so @var{mutex} is automatically unlocked if an
892 error or new continuation exits @var{body}, and is re-locked if
893 @var{body} is re-entered by a captured continuation.
896 @deffn macro monitor body@dots{}
897 Evaluate the @var{body} forms, with a mutex locked so only one thread
898 can execute that code at any one time. The return value is the return
899 from the last @var{body} form.
901 Each @code{monitor} form has its own private mutex and the locking and
902 evaluation is as per @code{with-mutex} above. A standard mutex
903 (@code{make-mutex}) is used, which means @var{body} must not
904 recursively re-enter the @code{monitor} form.
906 The term ``monitor'' comes from operating system theory, where it
907 means a particular bit of code managing access to some resource and
908 which only ever executes on behalf of one process at any one time.
912 The following provide access to standard mutexes from C code.
914 @deftp {C Data Type} scm_t_mutex
915 A mutex, to be used with @code{scm_mutex_init}, etc.
918 @deftypefn {C Function} void scm_mutex_init (scm_t_mutex *m)
919 Initialize the mutex structure pointed to by @var{m}.
922 @deftypefn {C Function} void scm_mutex_destroy (scm_t_mutex *m)
923 Free all resources associated with @var{m}.
926 @deftypefn {C Function} void scm_mutex_lock (scm_t_mutex *m)
927 Lock the mutex @var{m}. This is as per @code{lock-mutex} above on a
931 @deftypefn {C Function} int scm_mutex_trylock (scm_t_mutex *m)
932 Attempt to lock mutex @var{m}, as per @code{scm_mutex_lock}. If
933 @var{m} is unlocked then this is done and the return is non-zero. If
934 @var{m} is already locked by another thread then do nothing and return
938 @deftypefn {C Function} void scm_mutex_unlock (scm_t_mutex *m)
939 Unlock the mutex @var{m}. The mutex must have been locked by the
940 current thread, otherwise the behavior is undefined.
945 @c TeX-master: "guile.texi"