lib/silcutil/silcschedule.h

   1 /*
   2
   3   silcschedule.h
   4
   5   COPYRIGHT
   6
   7   Author: Pekka Riikonen <priikone@silcnet.org>
   8
   9   Copyright (C) 1998 - 2001 Pekka Riikonen
  10
  11   This program is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   This program is distributed in the hope that it will be useful,
  17   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19   GNU General Public License for more details.
  20
  21 */
  22
  23 /****h* silcutil/SILC Schedule Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  * The SILC Scheduler is the heart of any application. The scheduler provides
  28  * the application's main loop that can handle incoming data, outgoing data,
  29  * timeouts and dispatch different kind of tasks.
  30  *
  31  * The SILC Scheduler supports file descriptor based tasks, timeout tasks
  32  * and generic tasks. File descriptor tasks are tasks that perform some
  33  * operation over the specified file descriptor. These include network
  34  * connections, for example. The timeout tasks are timeouts that are executed
  35  * after the specified timeout has elapsed. The generic tasks are tasks that
  36  * apply to all registered file descriptors thus providing one task that
  37  * applies to many independent connections.
  38  *
  39  * The SILC Scheduler is designed to be the sole main loop of the application
  40  * so that the application does not need any other main loop.  However,
  41  * SILC Scheduler does support running the scheduler only once, so that the
  42  * scheduler does not block, and thus providing a possiblity that some
  43  * external main loop is run over the SILC Scheduler. However, these
  44  * applications are considered to be special cases.
  45  *
  46  * Typical application first initializes the scheduler and then registers
  47  * the very first tasks to the scheduler and then run the scheduler.  After
  48  * the scheduler's run function returns the application is considered to be
  49  * ended.
  50  *
  51  * On WIN32 systems the SILC Scheduler is too designed to work as the main
  52  * loop of the GUI application. It can handle all Windows messages and
  53  * it dispatches them from the scheduler, and thus makes it possible to
  54  * create GUI applications. The scheduler can also handle all kinds of
  55  * WIN32 handles, this includes sockets created by the SILC Net API routines,
  56  * WSAEVENT handle objects created by Winsock2 routines and arbitrary
  57  * WIN32 HANDLE objects.
  58  *
  59  * The SILC Scheduler supports multi-threads as well. The actual scheduler
  60  * must be run in single-thread but other threads may register new tasks
  61  * and unregister old tasks.  However, it is enforced that the actual
  62  * task is always run in the main thread.  The scheduler is context based
  63  * which makes it possible to allocate several schedulers for one application.
  64  * Since the scheduler must be run in single-thread, a multi-threaded
  65  * application could be created by allocating own scheduler for each of the
  66  * worker threads.
  67  *
  68  ***/
  69
  70 #ifndef SILCSCHEDULE_H
  71 #define SILCSCHEDULE_H
  72
  73 /****s* silcutil/SilcScheduleAPI/SilcSchedule
  74  *
  75  * NAME
  76  *
  77  *    typedef struct SilcScheduleStruct *SilcSchedule;
  78  *
  79  * DESCRIPTION
  80  *
  81  *    This context is the actual Scheduler and is allocated by
  82  *    the silc_schedule_init funtion.  The context is given as argument
  83  *    to all silc_schedule_* functions.  It must be freed by the
  84  *    silc_schedule_uninit function.
  85  *
  86  ***/
  87 typedef struct SilcScheduleStruct *SilcSchedule;
  88
  89 /****s* silcutil/SilcScheduleAPI/SilcTask
  90  *
  91  * NAME
  92  *
  93  *    typedef struct SilcTaskStruct *SilcTask;
  94  *
  95  * DESCRIPTION
  96  *
  97  *    This object represents one task in the scheduler.  It is allocated
  98  *    by the silc_schedule_task_add function and freed by one of the
  99  *    silc_schedule_task_del* functions.
 100  *
 101  ***/
 102 typedef struct SilcTaskStruct *SilcTask;
 103
 104 /****d* silcutil/SilcScheduleAPI/SilcTaskType
 105  *
 106  * NAME
 107  *
 108  *    typedef enum { ... } SilcTaskType;
 109  *
 110  * DESCRIPTION
 111  *
 112  *    SILC has three types of tasks, non-timeout tasks (tasks that perform
 113  *    over file descriptors), timeout tasks and generic tasks (tasks that
 114  *    apply to every file descriptor). This type is sent as argument for the
 115  *    task registering function, silc_schedule_task_add.
 116  *
 117  * SOURCE
 118  */
 119 typedef enum {
 120   /* File descriptor task that performs some event over file descriptors.
 121      These tasks are for example network connections. */
 122   SILC_TASK_FD,
 123
 124   /* Timeout tasks are tasks that are executed after the specified
 125      time has elapsed. After the task is executed the task is removed
 126      automatically from the scheduler. It is safe to re-register the
 127      task in task callback. It is also safe to unregister a task in
 128      the task callback. */
 129   SILC_TASK_TIMEOUT,
 130
 131   /* Generic tasks are non-timeout tasks and they apply to all file
 132      descriptors, except to those that have explicitly registered a
 133      non-timeout task. These tasks are there to make it simpler and faster
 134      to execute common code that applies to all connections. These are,
 135      for example, receiving packets from network and sending packets to
 136      network. It doesn't make much sense to register a task that receives
 137      a packet from network to every connection when you can have one task
 138      that applies to all connections. This is what generic tasks are for.
 139      Generic tasks are not bound to any specific file descriptor, however,
 140      the correct file descriptor must be passed as argument to task
 141      registering function. */
 142   SILC_TASK_GENERIC,
 143 } SilcTaskType;
 144 /***/
 145
 146 /****d* silcutil/SilcScheduleAPI/SilcTaskEvent
 147  *
 148  * NAME
 149  *
 150  *    typedef enum { ... } SilcTaskEvent;
 151  *
 152  * DESCRIPTION
 153  *
 154  *    SILC Task event types.  The event type indicates the occurred
 155  *    event of the task.  This type will be given as argument to the
 156  *    SilcTaskCallback function to indicate the event for the caller.
 157  *    The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller
 158  *    of the silc_schedule_set_listen_fd, if the caller needs to control
 159  *    the events for the task. The SILC_TASK_EXPIRE is set always only
 160  *    by the scheduler when timeout expires for timeout task.
 161  *
 162  * SOURCE
 163  */
 164 typedef enum {
 165   SILC_TASK_READ      = 0x0001,          /* Reading */
 166   SILC_TASK_WRITE     = 0x0002,          /* Writing */
 167   SILC_TASK_EXPIRE    = 0x0004,          /* Timeout */
 168   SILC_TASK_INTERRUPT = 0x0004,          /* Signal */
 169 } SilcTaskEvent;
 170 /***/
 171
 172 /****d* silcutil/SilcScheduleAPI/SilcTaskPriority
 173  *
 174  * NAME
 175  *
 176  *    typedef enum { ... } SilcTaskPriority;
 177  *
 178  * DESCRIPTION
 179  *
 180  *    Task priorities. Tasks may be registered with different priorities.
 181  *    This type defines the different task priorities. The priorities
 182  *    behaves same for all type of tasks, fd tasks, timeout tasks and
 183  *    generic tasks.
 184  *
 185  * SOURCE
 186  */
 187 typedef enum {
 188   /* Lowest priority. The task is scheduled to run after its timeout
 189      has expired only and only when every other task with higher priority
 190      has already been run. For non-timeout tasks this priority behaves
 191      same way. Life is not fair for tasks with this priority. */
 192   SILC_TASK_PRI_LOW,
 193
 194   /* Normal priority that is used mostly in SILC. This is priority that
 195      should always be used unless you specificly need some other priority.
 196      The scheduler will run this task as soon as its timeout has expired.
 197      For non-timeout tasks this priority behaves same way. Tasks are run
 198      in FIFO (First-In-First-Out) order. */
 199   SILC_TASK_PRI_NORMAL,
 200 } SilcTaskPriority;
 201 /***/
 202
 203 /****f* silcutil/SilcScheduleAPI/SilcTaskCallback
 204  *
 205  * SYNOPSIS
 206  *
 207  *    typedef void (*SilcTaskCallback)(SilcSchedule schedule,
 208  *                                     SilcTaskEvent type, SilcUInt32 fd,
 209  *                                     void *context);
 210  *
 211  * DESCRIPTION
 212  *
 213  *    The task callback function.  This function will be called by the
 214  *    scheduler when some event of the task is performed.  For example,
 215  *    when data is available from the connection this will be called.
 216  *
 217  *    The `schedule' is the scheduler context, the `type' is the indicated
 218  *    event, the `fd' is the file descriptor of the task and the `context'
 219  *    is a caller specified context. If multiple events occurred this
 220  *    callback is called separately for all events.
 221  *
 222  *    To specify task callback function in the application using the
 223  *    SILC_TASK_CALLBACK and SILC_TASK_CALLBACK_GLOBAL macros is
 224  *    recommended.
 225  *
 226  ***/
 227 typedef void (*SilcTaskCallback)(SilcSchedule schedule, SilcTaskEvent type,
 228                                  SilcUInt32 fd, void *context);
 229
 230 /* Macros */
 231
 232 /****d* silcutil/SilcScheduleAPI/SILC_ALL_TASKS
 233  *
 234  * NAME
 235  *
 236  *    #define SILC_ALL_TASKS ...
 237  *
 238  * DESCRIPTION
 239  *
 240  *    Marks for all tasks in the scheduler. This can be passed to
 241  *    silc_schedule_task_del function to delete all tasks at once.
 242  *
 243  * SOURCE
 244  */
 245 #define SILC_ALL_TASKS ((SilcTask)1)
 246 /***/
 247
 248 /****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
 249  *
 250  * NAME
 251  *
 252  *    #define SILC_TASK_CALLBACK ...
 253  *
 254  * DESCRIPTION
 255  *
 256  *    Generic macro to define task callback functions. This defines a
 257  *    static function with name `func' as a task callback function.
 258  *
 259  * SOURCE
 260  */
 261 #define SILC_TASK_CALLBACK(func)                                \
 262 static void func(SilcSchedule schedule, SilcTaskEvent type,     \
 263                  SilcUInt32 fd, void *context)
 264 /***/
 265
 266 /****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK_GLOBAL
 267  *
 268  * NAME
 269  *
 270  *    #define SILC_TASK_CALLBACK_GLOBAL ...
 271  *
 272  * DESCRIPTION
 273  *
 274  *    Generic macro to define task callback functions. This defines a
 275  *    function with name `func' as a task callback function.  This
 276  *    differs from SILC_TASK_CALLBACK in that the defined function is
 277  *    not static.
 278  *
 279  * SOURCE
 280  */
 281 #define SILC_TASK_CALLBACK_GLOBAL(func)                 \
 282 void func(SilcSchedule schedule, SilcTaskEvent type,    \
 283           SilcUInt32 fd, void *context)
 284 /***/
 285
 286 /* Prototypes */
 287
 288 /****f* silcutil/SilcScheduleAPI/silc_schedule_init
 289  *
 290  * SYNOPSIS
 291  *
 292  *    SilcSchedule silc_schedule_init(int max_tasks);
 293  *
 294  * DESCRIPTION
 295  *
 296  *    Initializes the scheduler. This returns the scheduler context that
 297  *    is given as argument usually to all silc_schedule_* functions.
 298  *    The `max_tasks' indicates the number of maximum tasks that the
 299  *    scheduler can handle.
 300  *
 301  ***/
 302 SilcSchedule silc_schedule_init(int max_tasks);
 303
 304 /****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
 305  *
 306  * SYNOPSIS
 307  *
 308  *    bool silc_schedule_uninit(SilcSchedule schedule);
 309  *
 310  * DESCRIPTION
 311  *
 312  *    Uninitializes the scheduler. This is called when the program is ready
 313  *    to end. This removes all tasks from the scheduler. Returns FALSE if the
 314  *    scheduler could not be uninitialized. This happens when the scheduler
 315  *    is still valid and silc_schedule_stop has not been called.
 316  *
 317  ***/
 318 bool silc_schedule_uninit(SilcSchedule schedule);
 319
 320 /****f* silcutil/SilcScheduleAPI/silc_schedule_reinit
 321  *
 322  * SYNOPSIS
 323  *
 324  *    SilcSchedule silc_schedule_reinit(int max_tasks);
 325  *
 326  * DESCRIPTION
 327  *
 328  *    This function can be called to enlarge the task handling capabilities
 329  *    of the scheduler indicated by `schedule'.  The `max_tasks' must be
 330  *    larger than what was set in silc_schedule_init function.  This function
 331  *    returns FALSE if it cannot reinit the scheduler.  This function does
 332  *    not do anything else except ready the scheduler to handle `max_tasks'
 333  *    number of tasks after this function returns.  It is safe to call this
 334  *    function at any time, and it is guaranteed that existing tasks remain
 335  *    as they are in the scheduler.
 336  *
 337  ***/
 338 bool silc_schedule_reinit(SilcSchedule schedule, int max_tasks);
 339
 340 /****f* silcutil/SilcScheduleAPI/silc_schedule_stop
 341  *
 342  * SYNOPSIS
 343  *
 344  *    void silc_schedule_stop(SilcSchedule schedule);
 345  *
 346  * DESCRIPTION
 347  *
 348  *    Stops the scheduler even if it is not supposed to be stopped yet.
 349  *    After calling this, one must call silc_schedule_uninit (after the
 350  *    silc_schedule has returned).  After this is called it is guaranteed
 351  *    that next time the scheduler enters the main loop it will be stopped.
 352  *    However, untill it enters the main loop it will not detect that
 353  *    it is stopped for example if this is called from another thread.
 354  *
 355  ***/
 356 void silc_schedule_stop(SilcSchedule schedule);
 357
 358 /****f* silcutil/SilcScheduleAPI/silc_schedule
 359  *
 360  * SYNOPSIS
 361  *
 362  *    void silc_schedule(SilcSchedule schedule);
 363  *
 364  * DESCRIPTION
 365  *
 366  *    The SILC scheduler. This is actually the main routine in SILC programs.
 367  *    When this returns the program is to be ended. Before this function can
 368  *    be called, one must call silc_schedule_init function.
 369  *
 370  ***/
 371 void silc_schedule(SilcSchedule schedule);
 372
 373 /****f* silcutil/SilcScheduleAPI/silc_schedule_one
 374  *
 375  * SYNOPSIS
 376  *
 377  *    bool silc_schedule_one(SilcSchedule schedule, int block);
 378  *
 379  * DESCRIPTION
 380  *
 381  *    Same as the silc_schedule but runs the scheduler only one round
 382  *    and then returns.  This function is handy when the SILC scheduler
 383  *    is used inside some other external scheduler, for example.  If
 384  *    the `timeout_usecs' is non-negative a timeout will be added to the
 385  *    scheduler.  The function will not return in this timeout unless
 386  *    some other event occurs.
 387  *
 388  ***/
 389 bool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
 390
 391 /****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup
 392  *
 393  * SYNOPSIS
 394  *
 395  *    void silc_schedule_wakeup(SilcSchedule schedule);
 396  *
 397  * DESCRIPTION
 398  *
 399  *    Wakes up the scheduler. This is used only in multi-threaded
 400  *    environments where threads may add new tasks or remove old tasks
 401  *    from the scheduler. This is called to wake up the scheduler in the
 402  *    main thread so that it detects the changes in the scheduler.
 403  *    If threads support is not compiled in this function has no effect.
 404  *    Implementation of this function may be platform specific.
 405  *
 406  ***/
 407 void silc_schedule_wakeup(SilcSchedule schedule);
 408
 409 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add
 410  *
 411  * SYNOPSIS
 412  *
 413  *    SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
 414  *                                    SilcTaskCallback callback,
 415  *                                    void *context,
 416  *                                    long seconds, long useconds,
 417  *                                    SilcTaskType type,
 418  *                                    SilcTaskPriority priority);
 419  *
 420  * DESCRIPTION
 421  *
 422  *    Registers a new task to the scheduler. This same function is used
 423  *    to register all types of tasks. The `type' argument tells what type
 424  *    of the task is. Note that when registering non-timeout tasks one
 425  *    should also pass 0 as timeout, as the timeout will be ignored anyway.
 426  *    Also, note, that one cannot register timeout task with 0 timeout.
 427  *    There cannot be zero timeouts, passing zero means no timeout is used
 428  *    for the task and SILC_TASK_FD is used as default task type in
 429  *    this case.
 430  *
 431  *    The `schedule' is the scheduler context. The `fd' is the file
 432  *    descriptor of the task. On WIN32 systems the `fd' is not actual
 433  *    file descriptor but some WIN32 event handle. On WIN32 system the `fd'
 434  *    may be a socket created by the SILC Net API routines, WSAEVENT object
 435  *    created by Winsock2 network routines or arbitrary WIN32 HANDLE object.
 436  *    On Unix systems the `fd' is always the real file descriptor.
 437  *
 438  *    The `callback' is the task callback that will be called when some
 439  *    event occurs for this task. The `context' is sent as argument to
 440  *    the task `callback' function. For timeout tasks the callback is
 441  *    called after the specified timeout has elapsed.
 442  *
 443  *    If the `type' is SILC_TASK_TIMEOUT then `seconds' and `useconds'
 444  *    may be non-zero.  Otherwise they should be zero. The `priority'
 445  *    indicates the priority of the task.
 446  *
 447  *    It is always safe to call this function in any place. New tasks
 448  *    may be added also in task callbacks, and in multi-threaded environment
 449  *    in other threads as well.
 450  *
 451  ***/
 452 SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
 453                                 SilcTaskCallback callback, void *context,
 454                                 long seconds, long useconds,
 455                                 SilcTaskType type,
 456                                 SilcTaskPriority priority);
 457
 458 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
 459  *
 460  * SYNOPSIS
 461  *
 462  *    void silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
 463  *
 464  * DESCRIPTION
 465  *
 466  *    Deletes the `task' from the scheduler indicated by the `schedule'.
 467  *    After deleting the task it is guaranteed that the task callback
 468  *    will not be called. If the `task' is SILC_ALL_TASKS then all
 469  *    tasks is removed from the scheduler.
 470  *
 471  *    It is safe to call this function in any place. Tasks may be removed
 472  *    in task callbacks (including in the task's own task callback) and
 473  *    in multi-threaded environment in other threads as well.
 474  *
 475  ***/
 476 void silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
 477
 478 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd
 479  *
 480  * SYNOPSIS
 481  *
 482  *    void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
 483  *
 484  * DESCRIPTION
 485  *
 486  *    Deletes a task from the scheduler by the specified `fd'.
 487  *
 488  *    It is safe to call this function in any place. Tasks may be removed
 489  *    in task callbacks (including in the task's own task callback) and
 490  *    in multi-threaded environment in other threads as well.
 491  *
 492  *    Note that generic tasks cannot be deleted using this function
 493  *    since generic tasks does not match any specific fd.
 494  *
 495  ***/
 496 void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
 497
 498 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
 499  *
 500  * SYNOPSIS
 501  *
 502  *    void silc_schedule_task_del_by_callback(SilcSchedule schedule,
 503  *                                            SilcTaskCallback callback);
 504  *
 505  * DESCRIPTION
 506  *
 507  *    Deletes a task from the scheduler by the specified `callback' task
 508  *    callback function.
 509  *
 510  *    It is safe to call this function in any place. Tasks may be removed
 511  *    in task callbacks (including in the task's own task callback) and
 512  *    in multi-threaded environment in other threads as well.
 513  *
 514  ***/
 515 void silc_schedule_task_del_by_callback(SilcSchedule schedule,
 516                                         SilcTaskCallback callback);
 517
 518 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context
 519  *
 520  * SYNOPSIS
 521  *
 522  *    void silc_schedule_task_del_by_context(SilcSchedule schedule,
 523  *                                           void *context);
 524  *
 525  * DESCRIPTION
 526  *
 527  *    Deletes a task from the scheduler by the specified `context'.
 528  *
 529  *    It is safe to call this function in any place. Tasks may be removed
 530  *    in task callbacks (including in the task's own task callback) and
 531  *    in multi-threaded environment in other threads as well.
 532  *
 533  ***/
 534 void silc_schedule_task_del_by_context(SilcSchedule schedule, void *context);
 535
 536 /****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
 537  *
 538  * SYNOPSIS
 539  *
 540  *    void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
 541  *                                     SilcTaskEvent mask);
 542  *
 543  * DESCRIPTION
 544  *
 545  *    Sets a file descriptor `fd' to be listened by the scheduler for
 546  *    `mask' events.  To tell scheduler not to listen anymore for this
 547  *    file descriptor call the silc_schedule_unset_listen_fd function.
 548  *    When new task is created with silc_schedule_task_add the event
 549  *    for the task's fd is initially set to SILC_TASK_READ. If you need
 550  *    to control the task's fd's events you must call this function
 551  *    whenever you need to change the events. This can be called multiple
 552  *    times to change the events.
 553  *
 554  ***/
 555 void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
 556                                  SilcTaskEvent mask);
 557
 558 /****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
 559  *
 560  * SYNOPSIS
 561  *
 562  *    void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
 563  *
 564  * DESCRIPTION
 565  *
 566  *    Tells the scheduler not to listen anymore for the specified
 567  *    file descriptor `fd'. No events will be detected for the `fd'
 568  *    after calling this function.
 569  *
 570  ***/
 571 void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
 572
 573 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_register
 574  *
 575  * SYNOPSIS
 576  *
 577  *    void silc_schedule_signal_register(SilcSchedule schedule,
 578  *                                       SilcUInt32 signal,
 579  *                                       SilcTaskCallback callback,
 580  *                                       void *context);
 581  *
 582  * DESCRIPTION
 583  *
 584  *    Register signal indicated by `signal' to the scheduler.  Application
 585  *    should register all signals it is going to use to the scheduler.
 586  *    The `callback' with `context' will be called after the application
 587  *    has called silc_schedule_signal_call function in the real signal
 588  *    callback.  Application is responsible of calling that, and the
 589  *    signal system will not work without calling silc_schedule_signal_call
 590  *    function.  The specified `signal' value will be also delivered to
 591  *    the `callback' as the fd-argument.  The event type in the callback
 592  *    will be SILC_TASK_INTERRUPT.  It is safe to use any SILC routines,
 593  *    in the `callback' since it is actually called after the signal really
 594  *    happened.
 595  *
 596  *    On platform that does not support signals calling this function has
 597  *    not effect.
 598  *
 599  * EXAMPLE
 600  *
 601  *    Typical signal usage case on Unix systems:
 602  *
 603  *    struct sigaction sa;
 604  *    sa.sa_handler = signal_handler;
 605  *    sigaction(SIGHUP, &sa, NULL);
 606  *    sigaction(SIGINT, &sa, NULL);
 607  *    silc_schedule_signal_register(schedule, SIGHUP, hup_signal, context);
 608  *    silc_schedule_signal_register(schedule, SIGINT, int_signal, context);
 609  *
 610  *    static void signal_handler(int sig)
 611  *    {
 612  *      silc_schedule_signal_call(schedule, sig);
 613  *    }
 614  *
 615  *    The `signal_handler' can be used as generic signal callback in the
 616  *    application that merely calls silc_schedule_signal_call, which then
 617  *    eventually will deliver for example the `hup_signal' callback.  The
 618  *    same `signal_handler' can be used with all signals.
 619  *
 620  ***/
 621 void silc_schedule_signal_register(SilcSchedule schedule, SilcUInt32 signal,
 622                                    SilcTaskCallback callback, void *context);
 623
 624 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_unregister
 625  *
 626  * SYNOPSIS
 627  *
 628  *    void silc_schedule_signal_unregister(SilcSchedule schedule,
 629  *                                         SilcUInt32 signal,
 630  *                                         SilcTaskCallback callback,
 631  *                                         void *context);
 632  *
 633  * DESCRIPTION
 634  *
 635  *    Unregister a signal indicated by `signal' from the scheduler.  On
 636  *    platform that does not support signals calling this function has no
 637  *    effect.
 638  *
 639  ***/
 640 void silc_schedule_signal_unregister(SilcSchedule schedule, SilcUInt32 signal,
 641                                      SilcTaskCallback callback, void *context);
 642
 643 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_call
 644  *
 645  * SYNOPSIS
 646  *
 647  *    void silc_schedule_signal_call(SilcSchedule schedule,
 648  *                                   SilcUInt32 signal);
 649  *
 650  * DESCRIPTION
 651  *
 652  *    Mark the `signal' to be called later.  Every signal that has been
 653  *    registered by silc_schedule_signal_register is delivered by calling
 654  *    this function.  When signal really occurs, the application is
 655  *    responsible of calling this function int the signal handler.  After
 656  *    signal is over the scheduler will then safely deliver the callback
 657  *    that was given to silc_schedule_signal_register function.
 658  *
 659  ***/
 660 void silc_schedule_signal_call(SilcSchedule schedule, SilcUInt32 signal);
 661
 662 #endif