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 |
|
|
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 |
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. |
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 |
|
|
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 |
|
|