libguile/async.c

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