/[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.3 by mvo, Tue Aug 13 22:05:46 2002 UTC revision 1.4 by mvo, Mon Oct 7 16:34:28 2002 UTC
# Line 7  plus the Cygnus programmer's manual; it Line 7  plus the Cygnus programmer's manual; it
7  reviewed and largely reorganized.]  reviewed and largely reorganized.]
8    
9  @menu  @menu
10  * Arbiters::            Synchronization primitives.  * Arbiters::                    Synchronization primitives.
11  * Asyncs::              Asynchronous procedure invocation.  * Asyncs::                      Asynchronous procedure invocation.
12  * Dynamic Roots::       Root frames of execution.  * Dynamic Roots::               Root frames of execution.
13  * Threads::             Multiple threads of execution.  * Threads::                     Multiple threads of execution.
14  * Fluids::              Thread-local variables.  * Fluids::                      Thread-local variables.
15  @end menu  @end menu
16    
17    
# Line 54  arbiter was locked. Otherwise, return @c Line 54  arbiter was locked. Otherwise, return @c
54  @section Asyncs  @section Asyncs
55    
56  @cindex asyncs  @cindex asyncs
57    @cindex user asyncs
58  @cindex system asyncs  @cindex system asyncs
59    
60  @c FIXME::martin: Review me!  @c FIXME::martin: Review me!
61    
62  An async is a pair of one thunk (a parameterless procedure) and a mark.  Asyncs are a means of deferring the excution of Scheme code until it is
63  Setting the mark on an async guarantees that the thunk will be executed  safe to do so.
 somewhen in the future (@dfn{asynchronously}).  Setting the mark more  
 than once is satisfied by one execution of the thunk.  
   
 Guile supports two types of asyncs: Normal asyncs and system asyncs.  
 They differ in that marked system asyncs are executed implicitly as soon  
 as possible, whereas normal asyncs have to be invoked explicitly.  
 System asyncs are held in an internal data structure and are maintained  
 by Guile.  
   
 Normal asyncs are created with @code{async}, system asyncs with  
 @code{system-async}.  They are marked with @code{async-mark} or  
 @code{system-async-mark}, respectively.  
64    
65  @deffn {Scheme Procedure} async thunk  Guile provides two kinds of asyncs that share the basic concept but are
66  @deffnx {C Function} scm_async (thunk)  otherwise quite different: system asyncs and user asyncs.  System asyncs
67  Create a new async for the procedure @var{thunk}.  are integrated into the core of Guile and are executed automatically
68  @end deffn  when the system is in a state to allow the execution of Scheme code.
69    For example, it is not possible to execute Scheme code in a POSIX signal
70  @deffn {Scheme Procedure} system-async thunk  handler, but such a signal handler can queue a system async to be
71  @deffnx {C Function} scm_system_async (thunk)  executed in the near future, when it is safe to do so.
72  Create a new async for the procedure @var{thunk}.  Also  
73  add it to the system's list of active async objects.  System asyncs can also be queued for threads other than the current one.
74  @end deffn  This way, you can cause threads to asynchronously execute arbitrary
75    code.
76    
77    User asyncs offer a convenient means of queueing procedures for future
78    execution and triggering this execution.  They will not be executed
79    automatically.
80    
81  @deffn {Scheme Procedure} async-mark a  @menu
82  @deffnx {C Function} scm_async_mark (a)  * System asyncs::              
83  Mark the async @var{a} for future execution.  * User asyncs::                
84  @end deffn  @end menu
   
 @deffn {Scheme Procedure} system-async-mark a  
 @deffnx {C Function} scm_system_async_mark (a)  
 Mark the async @var{a} for future execution.  
 @end deffn  
85    
86  As already mentioned above, system asyncs are executed automatically.  @node System asyncs
87  Normal asyncs have to be explicitly invoked by storing one or more of  @subsection System asyncs
 them into a list and passing them to @code{run-asyncs}.  
88    
89  @deffn {Scheme Procedure} run-asyncs list_of_a  To cause the future asynchronous execution of a procedure in a given
90  @deffnx {C Function} scm_run_asyncs (list_of_a)  thread, use @code{system-async-mark}.
 Execute all thunks from the asyncs of the list @var{list_of_a}.  
 @end deffn  
91    
92  Automatic invocation of system asyncs can be temporarily disabled by  Automatic invocation of system asyncs can be temporarily disabled by
93  calling @code{mask-signals} and @code{unmask-signals}.  Setting the mark  calling @code{mask-signals} and @code{unmask-signals}.  Setting the mark
# Line 110  run once execution is enabled again.  Pl Line 96  run once execution is enabled again.  Pl
96  procedures should always be paired, and they must not be nested, e.g. no  procedures should always be paired, and they must not be nested, e.g. no
97  @code{mask-signals} is allowed if another one is still active.  @code{mask-signals} is allowed if another one is still active.
98    
99    @deffn {Scheme procedure} system-async-mark proc [thread]
100    @deffnx {C Function} scm_system_async_mark (proc)
101    @deffnx {C Function} scm_system_async_mark_for_thread (proc, thread)
102    Mark @var{proc} (a procedure with zero arguments) for future execution
103    in @var{thread}.  When @var{proc} has already been marked for
104    @var{thread} but has not been executed yet, this call has no effect.
105    When @var{thread} is omitted, the thread that called
106    @code{system-async-mark} is used.
107    
108    This procedure is not safe to be called from signal handlers.  Use
109    @code{scm_sigaction} or @code{scm_sigaction_for_thread} to install
110    signal handlers.
111    @end deffn
112    
113  @deffn {Scheme Procedure} mask-signals  @deffn {Scheme Procedure} mask-signals
114  @deffnx {C Function} scm_mask_signals ()  @deffnx {C Function} scm_mask_signals ()
115  Mask signals. The returned value is not specified.  Mask signals. The returned value is not specified.
# Line 120  Mask signals. The returned value is not Line 120  Mask signals. The returned value is not
120  Unmask signals. The returned value is not specified.  Unmask signals. The returned value is not specified.
121  @end deffn  @end deffn
122    
123  @c FIXME::martin: Find an example for usage of `noop'.  What is that  @node User asyncs
124  @c procedure for anyway?  @subsection User asyncs
125    
126    A user async is a pair of a thunk (a parameterless procedure) and a
127    mark.  Setting the mark on a user async will cause the thunk to be
128    executed when the user async is passed to @code{run-asyncs}.  Setting
129    the mark more than once is satisfied by one execution of the thunk.
130    
131    User asyncs are created with @code{async}.  They are marked with
132    @code{async-mark}.
133    
134    @deffn {Scheme Procedure} async thunk
135    @deffnx {C Function} scm_async (thunk)
136    Create a new user async for the procedure @var{thunk}.
137    @end deffn
138    
139    @deffn {Scheme Procedure} async-mark a
140    @deffnx {C Function} scm_async_mark (a)
141    Mark the user async @var{a} for future execution.
142    @end deffn
143    
144  @deffn {Scheme Procedure} noop . args  @deffn {Scheme Procedure} run-asyncs list_of_a
145  @deffnx {C Function} scm_noop (args)  @deffnx {C Function} scm_run_asyncs (list_of_a)
146  Do nothing.  When called without arguments, return @code{#f},  Execute all thunks from the marked asyncs of the list @var{list_of_a}.
 otherwise return the first argument.  
147  @end deffn  @end deffn
148    
149    
# Line 259  When using Guile threads, keep in mind t Line 276  When using Guile threads, keep in mind t
276  executed in a new dynamic root.  executed in a new dynamic root.
277    
278  @menu  @menu
279  * Low level thread primitives::  * Low level thread primitives::  
280  * Higher level thread procedures::  * Higher level thread procedures::  
281  @end menu  @end menu
282    
283    

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4

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