Did the follwing renamings: scm_with_blocked_asyncs ->
[bpt/guile.git] / libguile / async.c
1 /* Copyright (C) 1995,1996,1997,1998,2000,2001, 2002, 2004 Free Software Foundation, Inc.
2 *
3 * This library is free software; you can redistribute it and/or
4 * modify it under the terms of the GNU Lesser General Public
5 * License as published by the Free Software Foundation; either
6 * version 2.1 of the License, or (at your option) any later version.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 * Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public
14 * License along with this library; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16 */
17
18
19 \f
20 #if HAVE_CONFIG_H
21 # include <config.h>
22 #endif
23
24 #include <signal.h>
25 #include "libguile/_scm.h"
26 #include "libguile/eval.h"
27 #include "libguile/throw.h"
28 #include "libguile/root.h"
29 #include "libguile/smob.h"
30 #include "libguile/lang.h"
31 #include "libguile/dynwind.h"
32 #include "libguile/deprecation.h"
33
34 #include "libguile/validate.h"
35 #include "libguile/async.h"
36
37 #ifdef HAVE_STRING_H
38 #include <string.h>
39 #endif
40 #ifdef HAVE_UNISTD_H
41 #include <unistd.h>
42 #endif
43
44 \f
45 /* {Asynchronous Events}
46 *
47 * There are two kinds of asyncs: system asyncs and user asyncs. The
48 * two kinds have some concepts in commen but work slightly
49 * differently and are not interchangeable.
50 *
51 * System asyncs are used to run arbitrary code at the next safe point
52 * in a specified thread. You can use them to trigger execution of
53 * Scheme code from signal handlers or to interrupt a thread, for
54 * example.
55 *
56 * Each thread has a list of 'activated asyncs', which is a normal
57 * Scheme list of procedures with zero arguments. When a thread
58 * executes a SCM_ASYNC_TICK statement (which is included in
59 * SCM_TICK), it will call all procedures on this list.
60 *
61 * Also, a thread will wake up when a procedure is added to its list
62 * of active asyncs and call them. After that, it will go to sleep
63 * again. (Not implemented yet.)
64 *
65 *
66 * User asyncs are a little data structure that consists of a
67 * procedure of zero arguments and a mark. There are functions for
68 * setting the mark of a user async and for calling all procedures of
69 * marked asyncs in a given list. Nothing you couldn't quickly
70 * implement yourself.
71 */
72
73
74 \f
75
76 /* User asyncs. */
77
78 static scm_t_bits tc16_async;
79
80 /* cmm: this has SCM_ prefix because SCM_MAKE_VALIDATE expects it.
81 this is ugly. */
82 #define SCM_ASYNCP(X) SCM_TYP16_PREDICATE (tc16_async, X)
83 #define VALIDATE_ASYNC(pos, a) SCM_MAKE_VALIDATE_MSG(pos, a, ASYNCP, "user async")
84
85 #define ASYNC_GOT_IT(X) (SCM_CELL_WORD_0 (X) >> 16)
86 #define SET_ASYNC_GOT_IT(X, V) (SCM_SET_CELL_WORD_0 ((X), SCM_TYP16 (X) | ((V) << 16)))
87 #define ASYNC_THUNK(X) SCM_CELL_OBJECT_1 (X)
88
89 static SCM
90 async_gc_mark (SCM obj)
91 {
92 return ASYNC_THUNK (obj);
93 }
94
95 SCM_DEFINE (scm_async, "async", 1, 0, 0,
96 (SCM thunk),
97 "Create a new async for the procedure @var{thunk}.")
98 #define FUNC_NAME s_scm_async
99 {
100 SCM_RETURN_NEWSMOB (tc16_async, SCM_UNPACK (thunk));
101 }
102 #undef FUNC_NAME
103
104 SCM_DEFINE (scm_async_mark, "async-mark", 1, 0, 0,
105 (SCM a),
106 "Mark the async @var{a} for future execution.")
107 #define FUNC_NAME s_scm_async_mark
108 {
109 VALIDATE_ASYNC (1, a);
110 SET_ASYNC_GOT_IT (a, 1);
111 return SCM_UNSPECIFIED;
112 }
113 #undef FUNC_NAME
114
115 SCM_DEFINE (scm_run_asyncs, "run-asyncs", 1, 0, 0,
116 (SCM list_of_a),
117 "Execute all thunks from the asyncs of the list @var{list_of_a}.")
118 #define FUNC_NAME s_scm_run_asyncs
119 {
120 while (! SCM_NULL_OR_NIL_P (list_of_a))
121 {
122 SCM a;
123 SCM_VALIDATE_CONS (1, list_of_a);
124 a = SCM_CAR (list_of_a);
125 VALIDATE_ASYNC (SCM_ARG1, a);
126 if (ASYNC_GOT_IT (a))
127 {
128 SET_ASYNC_GOT_IT (a, 0);
129 scm_call_0 (ASYNC_THUNK (a));
130 }
131 list_of_a = SCM_CDR (list_of_a);
132 }
133 return SCM_BOOL_T;
134 }
135 #undef FUNC_NAME
136
137 \f
138
139 /* System asyncs. */
140
141 void
142 scm_async_click ()
143 {
144 /* Reset pending_asyncs even when asyncs are blocked and not really
145 executed.
146 */
147
148 scm_root->pending_asyncs = 0;
149 if (scm_root->block_asyncs == 0)
150 {
151 SCM asyncs;
152 while (!SCM_NULLP(asyncs = scm_root->active_asyncs))
153 {
154 scm_root->active_asyncs = SCM_EOL;
155 do
156 {
157 scm_call_0 (SCM_CAR (asyncs));
158 asyncs = SCM_CDR (asyncs);
159 }
160 while (!SCM_NULLP(asyncs));
161 }
162 for (asyncs = scm_root->signal_asyncs; !SCM_NULLP(asyncs);
163 asyncs = SCM_CDR (asyncs))
164 {
165 if (!SCM_FALSEP (SCM_CAR (asyncs)))
166 {
167 SCM proc = SCM_CAR (asyncs);
168 SCM_SETCAR (asyncs, SCM_BOOL_F);
169 scm_call_0 (proc);
170 }
171 }
172 }
173 }
174
175 #if (SCM_ENABLE_DEPRECATED == 1)
176
177 SCM_DEFINE (scm_system_async, "system-async", 1, 0, 0,
178 (SCM thunk),
179 "This function is deprecated. You can use @var{thunk} directly\n"
180 "instead of explicitely creating an async object.\n")
181 #define FUNC_NAME s_scm_system_async
182 {
183 scm_c_issue_deprecation_warning
184 ("'system-async' is deprecated. "
185 "Use the procedure directly with 'system-async-mark'.");
186 return thunk;
187 }
188 #undef FUNC_NAME
189
190 #endif /* SCM_ENABLE_DEPRECATED == 1 */
191
192 void
193 scm_i_queue_async_cell (SCM c, scm_root_state *root)
194 {
195 SCM p = root->active_asyncs;
196 SCM_SETCDR (c, SCM_EOL);
197 if (p == SCM_EOL)
198 root->active_asyncs = c;
199 else
200 {
201 SCM pp;
202 while ((pp = SCM_CDR(p)) != SCM_EOL)
203 {
204 if (SCM_CAR (p) == SCM_CAR (c))
205 return;
206 p = pp;
207 }
208 SCM_SETCDR (p, c);
209 }
210 root->pending_asyncs = 1;
211 }
212
213 SCM_DEFINE (scm_system_async_mark_for_thread, "system-async-mark", 1, 1, 0,
214 (SCM proc, SCM thread),
215 "Mark @var{proc} (a procedure with zero arguments) for future execution\n"
216 "in @var{thread}. If @var{proc} has already been marked for\n"
217 "@var{thread} but has not been executed yet, this call has no effect.\n"
218 "If @var{thread} is omitted, the thread that called\n"
219 "@code{system-async-mark} is used.\n\n"
220 "This procedure is not safe to be called from C signal handlers. Use\n"
221 "@code{scm_sigaction} or @code{scm_sigaction_for_thread} to install\n"
222 "signal handlers.")
223 #define FUNC_NAME s_scm_system_async_mark_for_thread
224 {
225 if (SCM_UNBNDP (thread))
226 thread = scm_current_thread ();
227 else
228 {
229 SCM_VALIDATE_THREAD (2, thread);
230 if (scm_c_thread_exited_p (thread))
231 SCM_MISC_ERROR ("thread has already exited", SCM_EOL);
232 }
233 scm_i_queue_async_cell (scm_cons (proc, SCM_BOOL_F),
234 scm_i_thread_root (thread));
235 return SCM_UNSPECIFIED;
236 }
237 #undef FUNC_NAME
238
239 SCM
240 scm_system_async_mark (SCM proc)
241 #define FUNC_NAME s_scm_system_async_mark_for_thread
242 {
243 return scm_system_async_mark_for_thread (proc, SCM_UNDEFINED);
244 }
245 #undef FUNC_NAME
246
247 \f
248
249
250 SCM_DEFINE (scm_noop, "noop", 0, 0, 1,
251 (SCM args),
252 "Do nothing. When called without arguments, return @code{#f},\n"
253 "otherwise return the first argument.")
254 #define FUNC_NAME s_scm_noop
255 {
256 SCM_VALIDATE_REST_ARGUMENT (args);
257 return (SCM_NULL_OR_NIL_P (args) ? SCM_BOOL_F : SCM_CAR (args));
258 }
259 #undef FUNC_NAME
260
261
262 \f
263
264 #if (SCM_ENABLE_DEPRECATED == 1)
265
266 SCM_DEFINE (scm_unmask_signals, "unmask-signals", 0, 0, 0,
267 (),
268 "Unmask signals. The returned value is not specified.")
269 #define FUNC_NAME s_scm_unmask_signals
270 {
271 scm_c_issue_deprecation_warning
272 ("'unmask-signals' is deprecated. "
273 "Use 'call-with-blocked-asyncs' instead.");
274
275 if (scm_root->block_asyncs == 0)
276 SCM_MISC_ERROR ("signals already unmasked", SCM_EOL);
277 scm_root->block_asyncs = 0;
278 scm_async_click ();
279 return SCM_UNSPECIFIED;
280 }
281 #undef FUNC_NAME
282
283
284 SCM_DEFINE (scm_mask_signals, "mask-signals", 0, 0, 0,
285 (),
286 "Mask signals. The returned value is not specified.")
287 #define FUNC_NAME s_scm_mask_signals
288 {
289 scm_c_issue_deprecation_warning
290 ("'mask-signals' is deprecated. Use 'call-with-blocked-asyncs' instead.");
291
292 if (scm_root->block_asyncs > 0)
293 SCM_MISC_ERROR ("signals already masked", SCM_EOL);
294 scm_root->block_asyncs = 1;
295 return SCM_UNSPECIFIED;
296 }
297 #undef FUNC_NAME
298
299 #endif /* SCM_ENABLE_DEPRECATED == 1 */
300
301 static void
302 increase_block (void *unused)
303 {
304 scm_root->block_asyncs++;
305 }
306
307 static void
308 decrease_block (void *unused)
309 {
310 scm_root->block_asyncs--;
311 if (scm_root->block_asyncs == 0)
312 scm_async_click ();
313 }
314
315 SCM_DEFINE (scm_call_with_blocked_asyncs, "call-with-blocked-asyncs", 1, 0, 0,
316 (SCM proc),
317 "Call @var{proc} with no arguments and block the execution\n"
318 "of system asyncs by one level for the current thread while\n"
319 "it is running. Return the value returned by @var{proc}.\n")
320 #define FUNC_NAME s_scm_call_with_blocked_asyncs
321 {
322 return scm_internal_dynamic_wind (increase_block,
323 (scm_t_inner) scm_call_0,
324 decrease_block,
325 (void *)proc, NULL);
326 }
327 #undef FUNC_NAME
328
329 void *
330 scm_c_call_with_blocked_asyncs (void *(*proc) (void *data), void *data)
331 {
332 return (void *)scm_internal_dynamic_wind (increase_block,
333 (scm_t_inner) proc,
334 decrease_block,
335 data, NULL);
336 }
337
338
339 SCM_DEFINE (scm_call_with_unblocked_asyncs, "call-with-unblocked-asyncs", 1, 0, 0,
340 (SCM proc),
341 "Call @var{proc} with no arguments and unblock the execution\n"
342 "of system asyncs by one level for the current thread while\n"
343 "it is running. Return the value returned by @var{proc}.\n")
344 #define FUNC_NAME s_scm_call_with_unblocked_asyncs
345 {
346 if (scm_root->block_asyncs == 0)
347 SCM_MISC_ERROR ("asyncs already unblocked", SCM_EOL);
348 return scm_internal_dynamic_wind (decrease_block,
349 (scm_t_inner) scm_call_0,
350 increase_block,
351 (void *)proc, NULL);
352 }
353 #undef FUNC_NAME
354
355 void *
356 scm_c_call_with_unblocked_asyncs (void *(*proc) (void *data), void *data)
357 {
358 if (scm_root->block_asyncs == 0)
359 scm_misc_error ("scm_c_call_with_unblocked_asyncs",
360 "asyncs already unblocked", SCM_EOL);
361 return (void *)scm_internal_dynamic_wind (decrease_block,
362 (scm_t_inner) proc,
363 increase_block,
364 data, NULL);
365 }
366
367 void
368 scm_frame_block_asyncs ()
369 {
370 scm_frame_rewind (increase_block, NULL, SCM_F_WIND_EXPLICITLY);
371 scm_frame_unwind (decrease_block, NULL, SCM_F_WIND_EXPLICITLY);
372 }
373
374 void
375 scm_frame_unblock_asyncs ()
376 {
377 if (scm_root->block_asyncs == 0)
378 scm_misc_error ("scm_with_unblocked_asyncs",
379 "asyncs already unblocked", SCM_EOL);
380 scm_frame_rewind (decrease_block, NULL, SCM_F_WIND_EXPLICITLY);
381 scm_frame_unwind (increase_block, NULL, SCM_F_WIND_EXPLICITLY);
382 }
383
384
385 \f
386
387 void
388 scm_init_async ()
389 {
390 scm_asyncs = SCM_EOL;
391 tc16_async = scm_make_smob_type ("async", 0);
392 scm_set_smob_mark (tc16_async, async_gc_mark);
393
394 #include "libguile/async.x"
395 }
396
397 /*
398 Local Variables:
399 c-file-style: "gnu"
400 End:
401 */