289 |
@menu |
@menu |
290 |
* Low level thread primitives:: |
* Low level thread primitives:: |
291 |
* Higher level thread procedures:: |
* Higher level thread procedures:: |
292 |
|
* C level thread interface:: |
293 |
@end menu |
@end menu |
294 |
|
|
295 |
|
|
304 |
Evaluate @code{(thunk)} in a new thread, and new dynamic context, |
Evaluate @code{(thunk)} in a new thread, and new dynamic context, |
305 |
returning a new thread object representing the thread. |
returning a new thread object representing the thread. |
306 |
|
|
307 |
If an error occurs during evaluation, call error-handler, passing it an |
If an error occurs during evaluation, call error-handler, passing it |
308 |
error code describing the condition. [Error codes are currently |
an error code. If this happens, the error-handler is called outside |
309 |
meaningless integers. In the future, real values will be specified.] |
the scope of the new root -- it is called in the same dynamic context |
310 |
If this happens, the error-handler is called outside the scope of the new |
in which with-new-thread was evaluated, but not in the caller's |
311 |
root -- it is called in the same dynamic context in which |
thread. |
|
with-new-thread was evaluated, but not in the caller's thread. |
|
312 |
|
|
313 |
All the evaluation rules for dynamic roots apply to threads. |
All the evaluation rules for dynamic roots apply to threads. |
314 |
@end deffn |
@end deffn |
337 |
the calling thread owns the lock on @var{mutex}. Locking a mutex that |
the calling thread owns the lock on @var{mutex}. Locking a mutex that |
338 |
a thread already owns will succeed right away and will not block the |
a thread already owns will succeed right away and will not block the |
339 |
thread. That is, Guile's mutexes are @emph{recursive}. |
thread. That is, Guile's mutexes are @emph{recursive}. |
340 |
|
|
341 |
|
When a system async is activated for a thread that is blocked in a |
342 |
|
call to @code{lock-mutex}, the waiting is interrupted and the async is |
343 |
|
executed. When the async returns, the waiting is resumed. |
344 |
@end deffn |
@end deffn |
345 |
|
|
346 |
@deffn {Scheme Procedure} try-mutex mutex |
@deffn {Scheme Procedure} try-mutex mutex |
361 |
|
|
362 |
@c begin (texi-doc-string "guile" "make-condition-variable") |
@c begin (texi-doc-string "guile" "make-condition-variable") |
363 |
@deffn {Scheme Procedure} make-condition-variable |
@deffn {Scheme Procedure} make-condition-variable |
364 |
|
Make a new condition variable. |
365 |
@end deffn |
@end deffn |
366 |
|
|
367 |
@c begin (texi-doc-string "guile" "wait-condition-variable") |
@c begin (texi-doc-string "guile" "wait-condition-variable") |
371 |
is locked again when this function returns. When @var{time} is given, |
is locked again when this function returns. When @var{time} is given, |
372 |
it specifies a point in time where the waiting should be aborted. It |
it specifies a point in time where the waiting should be aborted. It |
373 |
can be either a integer as returned by @code{current-time} or a pair |
can be either a integer as returned by @code{current-time} or a pair |
374 |
as returned by @code{gettimeofday}. When the waiting is aborted the |
as returned by @code{gettimeofday}. When the waiting is aborted, |
375 |
mutex is locked and @code{#f} is returned. When the condition |
@code{#f} is returned. When the condition variable has in fact been |
376 |
variable is in fact signalled, the mutex is also locked and @code{#t} |
signalled, @code{#t} is returned. The mutex is re-locked in any case |
377 |
is returned. |
before @code{wait-condition-variable} returns. |
378 |
|
|
379 |
|
When a system async is activated for a thread that is blocked in a |
380 |
|
call to @code{wait-condition-variable}, the waiting is interrupted, |
381 |
|
the mutex is locked, and the async is executed. When the async |
382 |
|
returns, the mutex is unlocked again and the waiting is resumed. |
383 |
@end deffn |
@end deffn |
384 |
|
|
385 |
@c begin (texi-doc-string "guile" "signal-condition-variable") |
@c begin (texi-doc-string "guile" "signal-condition-variable") |
386 |
@deffn {Scheme Procedure} signal-condition-variable cond-var |
@deffn {Scheme Procedure} signal-condition-variable cond-var |
387 |
|
Wake up one thread that is waiting for @var{cv}. |
388 |
@end deffn |
@end deffn |
389 |
|
|
390 |
@c begin (texi-doc-string "guile" "broadcast-condition-variable") |
@c begin (texi-doc-string "guile" "broadcast-condition-variable") |
391 |
@deffn {Scheme Procedure} signal-condition-variable cond-var |
@deffn {Scheme Procedure} signal-condition-variable cond-var |
392 |
|
Wake up all threads that are waiting for @var{cv}. |
393 |
@end deffn |
@end deffn |
394 |
|
|
395 |
@node Higher level thread procedures |
@node Higher level thread procedures |
401 |
@code{(ice-9 threads)} module. These provide standardized |
@code{(ice-9 threads)} module. These provide standardized |
402 |
thread creation and mutex interaction. |
thread creation and mutex interaction. |
403 |
|
|
|
@deffn {Scheme Procedure} %thread-handler tag args@dots{} |
|
|
|
|
|
This procedure is specified as the standard error-handler for |
|
|
@code{make-thread} and @code{begin-thread}. If the number of @var{args} |
|
|
is three or more, use @code{display-error}, otherwise display a message |
|
|
"uncaught throw to @var{tag}". All output is sent to the port specified |
|
|
by @code{current-error-port}. |
|
|
|
|
|
Before display, global var @code{the-last-stack} is set to @code{#f} |
|
|
and signals are unmasked with @code{unmask-signals}. |
|
|
|
|
|
[FIXME: Why distinguish based on number of args?! Cue voodoo music here.] |
|
|
@end deffn |
|
|
|
|
404 |
@deffn macro make-thread proc [args@dots{}] |
@deffn macro make-thread proc [args@dots{}] |
405 |
Apply @var{proc} to @var{args} in a new thread formed by |
Apply @var{proc} to @var{args} in a new thread formed by |
406 |
@code{call-with-new-thread} using @code{%thread-handler} as the error |
@code{call-with-new-thread} using a default error handler that display |
407 |
handler. |
the error to the current error port. |
408 |
@end deffn |
@end deffn |
409 |
|
|
410 |
@deffn macro begin-thread first [rest@dots{}] |
@deffn macro begin-thread first [rest@dots{}] |
411 |
Evaluate forms @var{first} and @var{rest} in a new thread formed by |
Evaluate forms @var{first} and @var{rest} in a new thread formed by |
412 |
@code{call-with-new-thread} using @code{%thread-handler} as the error |
@code{call-with-new-thread} using a default error handler that display |
413 |
handler. |
the error to the current error port. |
414 |
@end deffn |
@end deffn |
415 |
|
|
416 |
@deffn macro with-mutex m [body@dots{}] |
@deffn macro with-mutex m [body@dots{}] |
421 |
@deffn macro monitor first [rest@dots{}] |
@deffn macro monitor first [rest@dots{}] |
422 |
Evaluate forms @var{first} and @var{rest} under a newly created |
Evaluate forms @var{first} and @var{rest} under a newly created |
423 |
anonymous mutex, using @code{with-mutex}. |
anonymous mutex, using @code{with-mutex}. |
|
|
|
|
[FIXME: Is there any way to access the mutex?] |
|
424 |
@end deffn |
@end deffn |
425 |
|
|
426 |
|
@node C level thread interface |
427 |
|
@subsection C level thread interface |
428 |
|
|
429 |
|
You can create and manage threads, mutexes, and condition variables |
430 |
|
with the C versions of the primitives above. For example, you can |
431 |
|
create a mutex with @code{scm_make_mutex} and lock it with |
432 |
|
@code{scm_lock_mutex}. In addition to these primitives there is also |
433 |
|
a second set of primitives for threading related things. These |
434 |
|
functions and data types are only available from C and can not be |
435 |
|
mixed with the first set from above. However, they might be more |
436 |
|
efficient and can be used in situations where Scheme data types are |
437 |
|
not allowed or are inconvenient to use. |
438 |
|
|
439 |
|
Furthermore, they are the primitives that Guile relies on for its own |
440 |
|
higher level threads. By reimplementing them, you can adapt Guile to |
441 |
|
different low-level thread implementations. |
442 |
|
|
443 |
|
@deftp {C Data Type} scm_t_thread |
444 |
|
This data type represents a thread, to be used with scm_thread_create, |
445 |
|
etc. |
446 |
|
@end deftp |
447 |
|
|
448 |
|
@deftypefun {C Function} int scm_thread_create (scm_t_thread *t, void (*proc)(void *), void *data) |
449 |
|
Create a new thread that will start by calling @var{proc}, passing it |
450 |
|
@var{data}. A handle for the new thread is stored in @var{t}, which |
451 |
|
must be non-NULL. The thread terminated when @var{proc} returns. |
452 |
|
When the thread has not been detached, its handle remains valid after |
453 |
|
is has terminated so that it can be used with @var{scm_thread_join}, |
454 |
|
for example. When it has been detached, the handle becomes invalid as |
455 |
|
soon as the thread terminates. |
456 |
|
@end deftypefun |
457 |
|
|
458 |
|
@deftypefun {C Function} void scm_thread_detach (scm_t_thread t) |
459 |
|
Detach the thread @var{t}. See @code{scm_thread_create}. |
460 |
|
@end deftypefun |
461 |
|
|
462 |
|
@deftypefun {C Function} void scm_thread_join (scm_t_thread t) |
463 |
|
Wait for thread @var{t} to terminate. The thread must not have been |
464 |
|
detached at the time that @code{scm_thread_join} is called, but it |
465 |
|
might have been detached by the time it terminates. |
466 |
|
@end deftypefun |
467 |
|
|
468 |
|
@deftypefun {C Function} scm_t_thread scm_thread_self () |
469 |
|
Return the handle of the calling thread. |
470 |
|
@end deftypefun |
471 |
|
|
472 |
|
@deftp {C Data Type} scm_t_mutex |
473 |
|
This data type represents a mutex, to be used with scm_mutex_init, |
474 |
|
etc. |
475 |
|
@end deftp |
476 |
|
|
477 |
|
@deftypefun {C Function} void scm_mutex_init (scm_t_mutex *m) |
478 |
|
Initialize the mutex structure pointed to by @var{m}. |
479 |
|
@end deftypefun |
480 |
|
|
481 |
|
@deftypefun {C Function} void scm_mutex_destroy (scm_t_mutex *m) |
482 |
|
Deallocate all resources associated with @var{m}. |
483 |
|
@end deftypefun |
484 |
|
|
485 |
|
@deftypefun {C Function} void scm_mutex_lock (scm_t_mutex *m) |
486 |
|
Lock the mutex @var{m}. When it is already locked by a different |
487 |
|
thread, wait until it becomes available. Locking a mutex that is |
488 |
|
already locked by the current threads is not allowd and results in |
489 |
|
undefined behavior. The mutices are not guaranteed to be fair. That |
490 |
|
is, a thread that attempts a lock after yourself might be granted it |
491 |
|
before you. |
492 |
|
@end deftypefun |
493 |
|
|
494 |
|
@deftypefun {C Function} int scm_mutex_trylock (scm_t_mutex *m) |
495 |
|
Lock @var{m} as with @code{scm_mutex_lock} but don't wait when this |
496 |
|
does succeed immediately. Returns non-zero when the mutex could in |
497 |
|
fact be locked , and zero when it is already locked by some other |
498 |
|
thread. |
499 |
|
@end deftypefun |
500 |
|
|
501 |
|
@deftypefun {C Function} void scm_mutex_unlock (scm_t_mutex *m) |
502 |
|
Unlock the mutex @var{m}. The mutex must have been locked by the |
503 |
|
current thread, else the behavior is undefined. |
504 |
|
@end deftypefun |
505 |
|
|
506 |
|
@deftp {C Data Type} scm_t_cond |
507 |
|
This data type represents a condition variable, to be used with |
508 |
|
scm_cond_init, etc. |
509 |
|
@end deftp |
510 |
|
|
511 |
|
@deftypefun {C Function} void scm_cond_init (scm_t_cond *c) |
512 |
|
Initialize the mutex structure pointed to by @var{c}. |
513 |
|
@end deftypefun |
514 |
|
|
515 |
|
@deftypefun {C Function} void scm_cond_destroy (scm_t_cond *c) |
516 |
|
Deallocate all resources associated with @var{c}. |
517 |
|
@end deftypefun |
518 |
|
|
519 |
|
@deftypefun {C Function} void scm_cond_wait (scm_t_cond *c, scm_t_mutex *m) |
520 |
|
Wait for @var{c} to be signalled. While waiting @var{m} is unlocked |
521 |
|
and locked again before @code{scm_cond_wait} returns. |
522 |
|
@end deftypefun |
523 |
|
|
524 |
|
@deftypefun {C Function} void scm_cond_timedwait (scm_t_cond *c, scm_t_mutex *m, timespec *abstime) |
525 |
|
Wait for @var{c} to be signalled as with @code{scm_cond_wait} but |
526 |
|
don't wait longer than the point in time specified by @var{abstime}. |
527 |
|
when the waiting is aborted, zero is returned; non-zero else. |
528 |
|
@end deftypefun |
529 |
|
|
530 |
|
@deftypefun {C Function} void scm_cond_signal (scm_t_cond *c) |
531 |
|
Signal the condition variable @var{c}. When one or more threads are |
532 |
|
waiting for it to be signalled, select one arbitrarily and let its |
533 |
|
wait succeed. |
534 |
|
@end deftypefun |
535 |
|
|
536 |
|
@deftypefun {C Function} void scm_cond_broadcast (scm_t_cond *c) |
537 |
|
Signal the condition variable @var{c}. When there are threads waiting |
538 |
|
for it to be signalled, wake them all up and make all their waits |
539 |
|
succeed. |
540 |
|
@end deftypefun |
541 |
|
|
542 |
|
@deftp {C Type} scm_t_key |
543 |
|
This type represents a key for a thread-specific value. |
544 |
|
@end deftp |
545 |
|
|
546 |
|
@deftypefun {C Function} void scm_key_create (scm_t_key *keyp) |
547 |
|
Create a new key for a thread-specific value. Each thread has its own |
548 |
|
value associated to such a handle. The new handle is stored into |
549 |
|
@var{keyp}, which must be non-NULL. |
550 |
|
@end deftypefun |
551 |
|
|
552 |
|
@deftypefun {C Function} void scm_key_delete (scm_t_key key) |
553 |
|
This function makes @var{key} invalid as a key for thread-specific data. |
554 |
|
@end deftypefun |
555 |
|
|
556 |
|
@deftypefun {C Function} void scm_key_setspecific (scm_t_key key, const void *value) |
557 |
|
Associate @var{value} with @var{key} in the calling thread. |
558 |
|
@end deftypefun |
559 |
|
|
560 |
|
@deftypefun {C Function} int scm_key_getspecific (scm_t_key key) |
561 |
|
Return the value currently associated with @var{key} in the calling |
562 |
|
thread. When @code{scm_key_setspecific} has not yet been called in |
563 |
|
this thread with this key, @code{NULL} is returned. |
564 |
|
@end deftypefun |
565 |
|
|
566 |
|
@deftypefun {C Function} int scm_thread_select (...) |
567 |
|
This function does the same thing as the system's @code{select} |
568 |
|
function, but in a way that is friendly to the thread implementation. |
569 |
|
You should call it in preference to the system @code{select}. |
570 |
|
@end deftypefun |
571 |
|
|
572 |
@node Fluids |
@node Fluids |
573 |
@section Fluids |
@section Fluids |
576 |
|
|
577 |
@c FIXME::martin: Review me! |
@c FIXME::martin: Review me! |
578 |
|
|
579 |
Fluids are objects to store values in. They have a few properties which |
Fluids are objects to store values in. They have a few properties |
580 |
make them useful in certain situations: Fluids can have one value per |
which make them useful in certain situations: Fluids can have one |
581 |
dynamic root (@pxref{Dynamic Roots}), so that changes to the value in a |
value per dynamic root (@pxref{Dynamic Roots}), so that changes to the |
582 |
fluid are only visible in the same dynamic root. Since threads are |
value in a fluid are only visible in the same dynamic root. Since |
583 |
executed in separate dynamic roots, fluids can be used for thread local |
threads are executed in separate dynamic roots, fluids can be used for |
584 |
storage (@pxref{Threads}). |
thread local storage (@pxref{Threads}). |
585 |
|
|
586 |
Fluids can be used to simulate the desirable effects of dynamically |
Fluids can be used to simulate the desirable effects of dynamically |
587 |
scoped variables. Dynamically scoped variables are useful when you |
scoped variables. Dynamically scoped variables are useful when you |