/[guile]/guile/guile-core/doc/ref/scheme-scheduling.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-scheduling.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.7 by mvo, Sun Oct 27 20:47:31 2002 UTC revision 1.8 by mvo, Mon Dec 2 01:04:28 2002 UTC
# Line 289  executed in a new dynamic root. Line 289  executed in a new dynamic root.
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    
# Line 303  executed in a new dynamic root. Line 304  executed in a new dynamic root.
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
# Line 337  blocks until the mutex becomes available Line 337  blocks until the mutex becomes available
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
# Line 357  with a call to @code{unlock-mutex}.  Onl Line 361  with a call to @code{unlock-mutex}.  Onl
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")
# Line 366  Wait until @var{cond-var} has been signa Line 371  Wait until @var{cond-var} has been signa
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
# Line 389  Higher level thread procedures are avail Line 401  Higher level thread procedures are avail
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{}]
# Line 423  These sub-operations form the branches o Line 421  These sub-operations form the branches o
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
# Line 435  anonymous mutex, using @code{with-mutex} Line 576  anonymous mutex, using @code{with-mutex}
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

Legend:
Removed from v.1.7  
changed lines
  Added in v.1.8

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26