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(pos, a, ASYNCP)
 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             "Register the procedure @var{proc} for future execution\n"
 232             "in @var{thread}.  When @var{thread} is not specified,\n"
 233             "use the current thread.")
 234 #define FUNC_NAME s_scm_system_async_mark_for_thread
 235 {
 236 #ifdef USE_THREADS
 237   if (SCM_UNBNDP (thread))
 238     thread = scm_current_thread ();
 239   else
 240     SCM_VALIDATE_THREAD (2, thread);
 241
 242   scm_i_queue_async_cell (scm_cons (proc, SCM_BOOL_F),
 243                           scm_i_thread_root (thread));
 244 #else
 245   scm_i_queue_async_cell (scm_cons (proc, SCM_BOOL_F), scm_root);
 246 #endif
 247   return SCM_UNSPECIFIED;
 248 }
 249 #undef FUNC_NAME
 250
 251 SCM
 252 scm_system_async_mark (SCM proc)
 253 #define FUNC_NAME s_scm_system_async_mark_for_thread
 254 {
 255   return scm_system_async_mark_for_thread (proc, SCM_UNDEFINED);
 256 }
 257 #undef FUNC_NAME
 258
 259 \f
 260
 261
 262 SCM_DEFINE (scm_noop, "noop", 0, 0, 1,
 263             (SCM args),
 264             "Do nothing.  When called without arguments, return @code{#f},\n"
 265             "otherwise return the first argument.")
 266 #define FUNC_NAME s_scm_noop
 267 {
 268   SCM_VALIDATE_REST_ARGUMENT (args);
 269   return (SCM_NULL_OR_NIL_P (args) ? SCM_BOOL_F : SCM_CAR (args));
 270 }
 271 #undef FUNC_NAME
 272
 273
 274 \f
 275
 276 #if (SCM_ENABLE_DEPRECATED == 1)
 277
 278 SCM_DEFINE (scm_unmask_signals, "unmask-signals", 0, 0, 0,
 279             (),
 280             "Unmask signals. The returned value is not specified.")
 281 #define FUNC_NAME s_scm_unmask_signals
 282 {
 283   scm_c_issue_deprecation_warning
 284     ("'unmask-signals' is deprecated.  "
 285      "Use 'call-with-blocked-asyncs' instead.");
 286
 287   if (scm_root->block_asyncs == 0)
 288     SCM_MISC_ERROR ("signals already unmasked", SCM_EOL);
 289   scm_root->block_asyncs = 0;
 290   return SCM_UNSPECIFIED;
 291 }
 292 #undef FUNC_NAME
 293
 294
 295 SCM_DEFINE (scm_mask_signals, "mask-signals", 0, 0, 0,
 296             (),
 297             "Mask signals. The returned value is not specified.")
 298 #define FUNC_NAME s_scm_mask_signals
 299 {
 300   scm_c_issue_deprecation_warning
 301     ("'mask-signals' is deprecated.  Use 'call-with-blocked-asyncs' instead.");
 302
 303   if (scm_root->block_asyncs > 0)
 304     SCM_MISC_ERROR ("signals already masked", SCM_EOL);
 305   scm_root->block_asyncs = 1;
 306   return SCM_UNSPECIFIED;
 307 }
 308 #undef FUNC_NAME
 309
 310 #endif /* SCM_ENABLE_DEPRECATED == 1 */
 311
 312 static void
 313 increase_block (void *unused)
 314 {
 315   scm_root->block_asyncs++;
 316 }
 317
 318 static void
 319 decrease_block (void *unused)
 320 {
 321   scm_root->block_asyncs--;
 322 }
 323
 324 SCM_DEFINE (scm_call_with_blocked_asyncs, "call-with-blocked-asyncs", 1, 0, 0,
 325             (SCM proc),
 326             "Call @var{proc} with no arguments and block the execution\n"
 327             "of system asyncs by one level for the current thread while\n"
 328             "it is running.  Return the value returned by @var{proc}.\n")
 329 #define FUNC_NAME s_scm_call_with_blocked_asyncs
 330 {
 331   return scm_internal_dynamic_wind (increase_block,
 332                                     (scm_t_inner) scm_call_0,
 333                                     decrease_block,
 334                                     proc, NULL);
 335 }
 336 #undef FUNC_NAME
 337
 338 void *
 339 scm_c_call_with_blocked_asyncs (void *(*proc) (void *data), void *data)
 340 {
 341   return scm_internal_dynamic_wind (increase_block,
 342                                     (scm_t_inner) proc,
 343                                     decrease_block,
 344                                     data, NULL);
 345 }
 346
 347
 348 SCM_DEFINE (scm_call_with_unblocked_asyncs, "call-with-unblocked-asyncs", 1, 0, 0,
 349             (SCM proc),
 350             "Call @var{proc} with no arguments and unblock the execution\n"
 351             "of system asyncs by one level for the current thread while\n"
 352             "it is running.  Return the value returned by @var{proc}.\n")
 353 #define FUNC_NAME s_scm_call_with_unblocked_asyncs
 354 {
 355   if (scm_root->block_asyncs == 0)
 356     SCM_MISC_ERROR ("asyncs already unblocked", SCM_EOL);
 357   return scm_internal_dynamic_wind (decrease_block,
 358                                     (scm_t_inner) scm_call_0,
 359                                     increase_block,
 360                                     proc, NULL);
 361 }
 362 #undef FUNC_NAME
 363
 364 void *
 365 scm_c_call_with_unblocked_asyncs (void *(*proc) (void *data), void *data)
 366 {
 367   if (scm_root->block_asyncs == 0)
 368     scm_misc_error ("scm_c_call_with_unblocked_asyncs",
 369                     "asyncs already unblocked", SCM_EOL);
 370   return scm_internal_dynamic_wind (decrease_block,
 371                                      (scm_t_inner) proc,
 372                                     increase_block,
 373                                     data, NULL);
 374 }
 375
 376 \f
 377
 378 void
 379 scm_init_async ()
 380 {
 381   scm_asyncs = SCM_EOL;
 382   tc16_async = scm_make_smob_type ("async", 0);
 383   scm_set_smob_mark (tc16_async, async_gc_mark);
 384
 385 #include "libguile/async.x"
 386 }
 387
 388 /*
 389   Local Variables:
 390   c-file-style: "gnu"
 391   End:
 392 */