lib/silcutil/silcschedule.h

   1 /*
   2
   3   silcschedule.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1998 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Schedule Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * The SILC Scheduler is the heart of any application. The scheduler provides
  25  * the application's main loop that can handle incoming data, outgoing data,
  26  * timeouts and dispatch different kind of tasks.
  27  *
  28  * The SILC Scheduler supports file descriptor based tasks and timeout tasks.
  29  * File descriptor tasks are tasks that perform some operation over the
  30  * specified file descriptor. These include network connections, for example.
  31  * The timeout tasks are timeouts that are executed after the specified
  32  * timeout has elapsed.
  33  *
  34  * The SILC Scheduler is designed to be the sole main loop of the application
  35  * so that the application does not need any other main loop.  However,
  36  * SILC Scheduler does support running the scheduler only once, so that the
  37  * scheduler does not block, and thus providing a possiblity that some
  38  * external main loop is run over the SILC Scheduler.
  39  *
  40  * Typical application first initializes the scheduler and then registers
  41  * the very first tasks to the scheduler and then run the scheduler.  After
  42  * the scheduler's run function returns the application is considered to be
  43  * ended.
  44  *
  45  * On WIN32 systems the SILC Scheduler is too designed to work as the main
  46  * loop of the GUI application. It can handle all Windows messages and
  47  * it dispatches them from the scheduler, and thus makes it possible to
  48  * create GUI applications. The scheduler can also handle all kinds of
  49  * WIN32 handles, this includes sockets created by the SILC Net API routines,
  50  * WSAEVENT handle objects created by Winsock2 routines and arbitrary
  51  * WIN32 HANDLE objects.
  52  *
  53  * The SILC Scheduler supports multi-threads as well. The actual scheduler
  54  * must be run in single-thread but other threads may register new tasks
  55  * and unregister old tasks.  However, it is enforced that the actual
  56  * task is always run in the main thread.  The scheduler is context based
  57  * which makes it possible to allocate several schedulers for one application.
  58  * Since the scheduler must be run in single-thread, a multi-threaded
  59  * application could be created by allocating own scheduler for each of the
  60  * worker threads.
  61  *
  62  ***/
  63
  64 #ifndef SILCSCHEDULE_H
  65 #define SILCSCHEDULE_H
  66
  67 /****s* silcutil/SilcScheduleAPI/SilcSchedule
  68  *
  69  * NAME
  70  *
  71  *    typedef struct SilcScheduleStruct *SilcSchedule;
  72  *
  73  * DESCRIPTION
  74  *
  75  *    This context is the actual Scheduler and is allocated by
  76  *    the silc_schedule_init funtion.  The context is given as argument
  77  *    to all silc_schedule_* functions.  It must be freed by the
  78  *    silc_schedule_uninit function.
  79  *
  80  ***/
  81 typedef struct SilcScheduleStruct *SilcSchedule;
  82
  83 /****s* silcutil/SilcScheduleAPI/SilcTask
  84  *
  85  * NAME
  86  *
  87  *    typedef struct SilcTaskStruct *SilcTask;
  88  *
  89  * DESCRIPTION
  90  *
  91  *    This object represents one task in the scheduler.  It is allocated
  92  *    by the silc_schedule_task_add function and freed by one of the
  93  *    silc_schedule_task_del* functions.
  94  *
  95  ***/
  96 typedef struct SilcTaskStruct *SilcTask;
  97
  98 /****d* silcutil/SilcScheduleAPI/SilcTaskEvent
  99  *
 100  * NAME
 101  *
 102  *    typedef enum { ... } SilcTaskEvent;
 103  *
 104  * DESCRIPTION
 105  *
 106  *    SILC Task event types.  The event type indicates the occurred
 107  *    event of the task.  This type will be given as argument to the
 108  *    SilcTaskCallback function to indicate the event for the caller.
 109  *    The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller
 110  *    of the silc_schedule_set_listen_fd, if the caller needs to control
 111  *    the events for the task. The SILC_TASK_EXPIRE is set always only
 112  *    by the scheduler when timeout expires for timeout task.  The
 113  *    SILC_TASK_INTERRUPT is set for signal callback.
 114  *
 115  * SOURCE
 116  */
 117 typedef enum {
 118   SILC_TASK_READ         = 0x0001,               /* Reading */
 119   SILC_TASK_WRITE        = 0x0002,               /* Writing */
 120   SILC_TASK_EXPIRE       = 0x0004,               /* Timeout */
 121   SILC_TASK_INTERRUPT    = 0x0008,               /* Signal */
 122 } SilcTaskEvent;
 123 /***/
 124
 125 /****f* silcutil/SilcScheduleAPI/SilcTaskCallback
 126  *
 127  * SYNOPSIS
 128  *
 129  *    typedef void (*SilcTaskCallback)(SilcSchedule schedule,
 130  *                                     void *app_context,
 131  *                                     SilcTaskEvent type, SilcUInt32 fd,
 132  *                                     void *context);
 133  *
 134  * DESCRIPTION
 135  *
 136  *    The task callback function.  This function will be called by the
 137  *    scheduler when some event of the task is performed.  For example,
 138  *    when data is available from the connection this will be called.
 139  *
 140  *    The `schedule' is the scheduler context, the `type' is the indicated
 141  *    event, the `fd' is the file descriptor of the task and the `context'
 142  *    is a caller specified context. If multiple events occurred this
 143  *    callback is called separately for all events.  The `app_context'
 144  *    is application specific context that was given as argument to the
 145  *    silc_schedule_init function.  If the task is timeout task then `fd'
 146  *    is zero (0).
 147  *
 148  *    To specify task callback function in the application using the
 149  *    SILC_TASK_CALLBACK macro is recommended.
 150  *
 151  *    The callback should not perform lenghty or blocking operations as
 152  *    this would also block all other waiting tasks.  The task callback
 153  *    should either handle the operation fast or issue an asynchronous
 154  *    call (like to register 0 timeout task) to handle it later.
 155  *
 156  ***/
 157 typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context,
 158                                  SilcTaskEvent type, SilcUInt32 fd,
 159                                  void *context);
 160
 161 /****f* silcutil/SilcScheduleAPI/SilcTaskEventCallback
 162  *
 163  * SYNOPSIS
 164  *
 165  *    typedef void (*SilcTaskEventCallback)(SilcSchedule schedule,
 166  *                                          void *app_context,
 167  *                                          SilcTask task, void *context,
 168  *                                          va_list va);
 169  *
 170  * DESCRIPTION
 171  *
 172  *    Task callback for event tasks added with silc_schedule_task_add_event.
 173  *    The callback of this type is called when an event task is signalled.
 174  *    The signal is delivered to all that have connected to the event.
 175  *
 176  *    The `task' is the event task.  The `context' is the context given as
 177  *    argument to silc_schedule_event_connect.  The `schedule' is the
 178  *    scheduler given as argument to silc_schedule_event_connect.
 179  *
 180  *    If FALSE is returned in this callback function the signal delivery to
 181  *    other connected entities is stopped.  Normally, TRUE is returned.
 182  *    If the `task' is deleted in this callback, the signal delivery is also
 183  *    stopped.
 184  *
 185  *    To specify task event callback function in the application using the
 186  *    SILC_TASK_EVENT_CALLBACK macro is recommended.
 187  *
 188  ***/
 189 typedef SilcBool (*SilcTaskEventCallback)(SilcSchedule schedule,
 190                                           void *app_context,
 191                                           SilcTask task, void *context,
 192                                           va_list va);
 193
 194 /****f* silcutil/SilcScheduleAPI/SilcTaskNotifyCb
 195  *
 196  * SYNOPSIS
 197  *
 198  *    typedef void (*SilcTaskNotifyCb)(SilcSchedule schedule,
 199  *                                     SilcBool added, SilcTask task,
 200  *                                     SilcBool fd_task, SilcUInt32 fd,
 201  *                                     SilcTaskEvent event,
 202  *                                     long seconds, long useconds,
 203  *                                     void *context);
 204  *
 205  * DESCRIPTION
 206  *
 207  *    Task notify callback.  Callback of this type can be set to scheduler
 208  *    by calling silc_schedule_set_notify and will be called whenever new
 209  *    task is added or old task is removed.  If `added' is TRUE then `task'
 210  *    is added to scheduler.  If `added' is FALSE then `task' will be removed
 211  *    from the scheduler.  If `fd_task' is TRUE the `task' is file descriptor
 212  *    task and has `fd' is its file descriptor.  If `fd_task' is FALSE then
 213  *    the task is timeout task and `seconds' and `useconds' specify the
 214  *    timeout.  The `context' is the context given to silc_schedule_set_notify.
 215  *
 216  * NOTES
 217  *
 218  *    The `schedule' is locked while this callback is called.  This means that
 219  *    new tasks cannot be added or removed inside this callback.
 220  *
 221  *    When timeout task expires this callback is not called.  This is called
 222  *    only when task is explicitly deleted from the scheduler.  Note that,
 223  *    when timeout task expires it is removed from the scheduler and `task'
 224  *    will become invalid.
 225  *
 226  *    If fd task changes its events, this will be called as if it was a new
 227  *    task with different `event' mask.
 228  *
 229  ***/
 230 typedef void (*SilcTaskNotifyCb)(SilcSchedule schedule,
 231                                  SilcBool added, SilcTask task,
 232                                  SilcBool fd_task, SilcUInt32 fd,
 233                                  SilcTaskEvent event,
 234                                  long seconds, long useconds,
 235                                  void *app_context);
 236
 237 /* Macros */
 238
 239 /****d* silcutil/SilcScheduleAPI/SILC_ALL_TASKS
 240  *
 241  * NAME
 242  *
 243  *    #define SILC_ALL_TASKS ...
 244  *
 245  * DESCRIPTION
 246  *
 247  *    Marks for all tasks in the scheduler. This can be passed to
 248  *    silc_schedule_task_del function to delete all tasks at once.
 249  *
 250  * SOURCE
 251  */
 252 #define SILC_ALL_TASKS ((SilcTask)1)
 253 /***/
 254
 255 /****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
 256  *
 257  * NAME
 258  *
 259  *    #define SILC_TASK_CALLBACK ...
 260  *
 261  * DESCRIPTION
 262  *
 263  *    Generic macro to declare task callback functions. This defines a
 264  *    function with name `func' as a task callback function.
 265  *
 266  * SOURCE
 267  */
 268 #define SILC_TASK_CALLBACK(func)                                        \
 269 void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \
 270           SilcUInt32 fd, void *context)
 271 /***/
 272
 273 /****d* silcutil/SilcScheduleAPI/SILC_TASK_EVENT_CALLBACK
 274  *
 275  * NAME
 276  *
 277  *    #define SILC_TASK_EVENT_CALLBACK ...
 278  *
 279  * DESCRIPTION
 280  *
 281  *    Generic macro to declare event task callback functions. This defines a
 282  *    function with name `func' as a event task callback function.
 283  *
 284  * SOURCE
 285  */
 286 #define SILC_TASK_EVENT_CALLBACK(func)                                  \
 287 SilcBool func(SilcSchedule schedule, void *app_context,                 \
 288               SilcTask task, void *context, va_list va)
 289
 290 /***/
 291
 292 /* Prototypes */
 293
 294 #include "silcschedule_i.h"
 295
 296 /****f* silcutil/SilcScheduleAPI/silc_schedule_init
 297  *
 298  * SYNOPSIS
 299  *
 300  *    SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
 301  *                                    SilcStack stack, SilcSchedule parent);
 302  *
 303  * DESCRIPTION
 304  *
 305  *    Initializes the scheduler. This returns the scheduler context or NULL
 306  *    on error.  The `app_context' is application specific context that is
 307  *    delivered to all task callbacks. The caller must free that context.
 308  *
 309  *    The `max_tasks' is the maximum number of file descriptor and socket
 310  *    tasks in the scheduler.  Set value to 0 to use default.  Operating
 311  *    system will enforce the final limit.  On some operating systems the
 312  *    limit can be significantly increased when this function is called in
 313  *    priviliged mode (as super user).
 314  *
 315  *    If `parent' is non-NULL it will be the parent of the new scheduler.
 316  *    If it is NULL this will create a new parent scheduler.  If `parent'
 317  *    is already a child scheduler, this will create a new child to the
 318  *    child's parent.  Even if `parent' is non-NULL the new child scheduler
 319  *    is still independent scheduler and will run independently of its
 320  *    parent.  However, each child and parent will share event tasks
 321  *    added with silc_schedule_task_add_event.
 322  *
 323  *    If `stack' is non-NULL all memory allocation for the scheduler is done
 324  *    from the `stack'.  Scheduler's stack may be retrieved by calling
 325  *    silc_schedule_get_stack.  A stack is created for scheduler always even
 326  *    if `stack' is NULL.  If it is non-NULL the created stack is a child
 327  *    stack using `stack' as its parent.  This means that memory allocated
 328  *    by the scheduler will be returned to the `stack' when scheduler is
 329  *    destroyed.
 330  *
 331  ***/
 332 SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
 333                                 SilcStack stack, SilcSchedule parent);
 334
 335 /****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
 336  *
 337  * SYNOPSIS
 338  *
 339  *    SilcBool silc_schedule_uninit(SilcSchedule schedule);
 340  *
 341  * DESCRIPTION
 342  *
 343  *    Uninitializes the scheduler. This is called when the program is ready
 344  *    to end. This removes all tasks from the scheduler. Returns FALSE if the
 345  *    scheduler could not be uninitialized. This happens when the scheduler
 346  *    is still valid and silc_schedule_stop has not been called.
 347  *
 348  *    If SilcStack was given to silc_schedule_init all memory allocated
 349  *    during the life time of the scheduler will be returned back to the
 350  *    given stack.
 351  *
 352  ***/
 353 SilcBool silc_schedule_uninit(SilcSchedule schedule);
 354
 355 /****f* silcutil/SilcScheduleAPI/silc_schedule_stop
 356  *
 357  * SYNOPSIS
 358  *
 359  *    void silc_schedule_stop(SilcSchedule schedule);
 360  *
 361  * DESCRIPTION
 362  *
 363  *    Stops the scheduler even if it is not supposed to be stopped yet.
 364  *    After calling this, one must call silc_schedule_uninit (after the
 365  *    silc_schedule has returned).  After this is called it is guaranteed
 366  *    that next time the scheduler enters the main loop it will be stopped.
 367  *    However, untill it enters the main loop it will not detect that
 368  *    it is stopped for example if this is called from another thread.
 369  *
 370  ***/
 371 void silc_schedule_stop(SilcSchedule schedule);
 372
 373 /****f* silcutil/SilcScheduleAPI/silc_schedule
 374  *
 375  * SYNOPSIS
 376  *
 377  *    void silc_schedule(SilcSchedule schedule);
 378  *
 379  * DESCRIPTION
 380  *
 381  *    The SILC scheduler.  The program will run inside this function.
 382  *    When this returns the program is to be ended.  Before this function
 383  *    can be called, one must call silc_schedule_init function.
 384  *
 385  * NOTES
 386  *
 387  *    On Windows this will block the calling thread but will continue
 388  *    to dispatch window messages, and thus can be used as the main loop
 389  *    of the program.
 390  *
 391  *    On Symbian this will block the calling thread.  The Symbian Active
 392  *    Scheduler must be running before calling this function.
 393  *
 394  ***/
 395 void silc_schedule(SilcSchedule schedule);
 396
 397 /****f* silcutil/SilcScheduleAPI/silc_schedule_one
 398  *
 399  * SYNOPSIS
 400  *
 401  *    SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
 402  *
 403  * DESCRIPTION
 404  *
 405  *    Same as the silc_schedule but runs the scheduler only one round
 406  *    and then returns.  This function is handy when the SILC scheduler
 407  *    is used inside some other external scheduler, for example.  If
 408  *    the `timeout_usecs' is non-negative a timeout will be added to the
 409  *    scheduler.  The function will not return in this timeout unless
 410  *    some other event occurs.
 411  *
 412  *    Typically this would be called from a timeout or idle task
 413  *    periodically (typically from 5-50 ms) to schedule SILC tasks.  In
 414  *    this case the `timeout_usecs' is usually 0 to make the function
 415  *    return immediately.
 416  *
 417  ***/
 418 SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
 419
 420 /****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup
 421  *
 422  * SYNOPSIS
 423  *
 424  *    void silc_schedule_wakeup(SilcSchedule schedule);
 425  *
 426  * DESCRIPTION
 427  *
 428  *    Wakes up the scheduler. This is may be used in multi-threaded
 429  *    environments where threads may add new tasks or remove old tasks
 430  *    from the scheduler. This is called to wake up the scheduler in the
 431  *    main thread so that it detects the changes in the scheduler.
 432  *    If threads support is not compiled in this function has no effect.
 433  *
 434  ***/
 435 void silc_schedule_wakeup(SilcSchedule schedule);
 436
 437 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_parent
 438  *
 439  * SYNOPSIS
 440  *
 441  *    SilcSchedule silc_schedule_get_parent(SilcSchedule schedule);
 442  *
 443  * DESCRIPTION
 444  *
 445  *    Returns the parent scheduler of the `schedule'.  Never returns NULL.
 446  *
 447  ***/
 448 SilcSchedule silc_schedule_get_parent(SilcSchedule schedule);
 449
 450 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_context
 451  *
 452  * SYNOPSIS
 453  *
 454  *    void *silc_schedule_get_context(SilcSchedule schedule);
 455  *
 456  * DESCRIPTION
 457  *
 458  *    Returns the application specific context that was saved into the
 459  *    scheduler in silc_schedule_init function.  The context is also
 460  *    returned to application in the SilcTaskCallback, but this function
 461  *    may be used to get it as well if needed.
 462  *
 463  ***/
 464 void *silc_schedule_get_context(SilcSchedule schedule);
 465
 466 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_stack
 467  *
 468  * SYNOPSIS
 469  *
 470  *    SilcStack silc_schedule_get_stack(SilcSchedule schedule);
 471  *
 472  * DESCRIPTION
 473  *
 474  *    Returns the stack of the `schedule'.  If it is used to make memory
 475  *    allocations outside the scheduler, it is recommended that a new
 476  *    child stack is created by using the returned stack as a parent and
 477  *    using the child stack to make the memory allocations.
 478  *
 479  ***/
 480 SilcStack silc_schedule_get_stack(SilcSchedule schedule);
 481
 482 /****f* silcutil/SilcScheduleAPI/silc_schedule_set_notify
 483  *
 484  * SYNOPSIS
 485  *
 486  *    void silc_schedule_set_notify(SilcSchedule schedule,
 487  *                                  SilcTaskNotifyCb notify, void *context);
 488  *
 489  * DESCRIPTION
 490  *
 491  *    Set notify callback to scheduler.  The `notify' will be called whenever
 492  *    task is added to or deleted from scheduler.
 493  *
 494  ***/
 495 void silc_schedule_set_notify(SilcSchedule schedule,
 496                               SilcTaskNotifyCb notify, void *context);
 497
 498 /****f* silcutil/SilcScheduleAPI/silc_schedule_set_global
 499  *
 500  * SYNOPSIS
 501  *
 502  *    void silc_schedule_set_global(SilcSchedule schedule);
 503  *
 504  * DESCRIPTION
 505  *
 506  *    Sets global SilcSchedule `schedule' that can be retrieved at any time
 507  *    by using silc_schedule_get_global.  The global scheduler is global only
 508  *    to the current thread.  Each thread can have their own global scheduler.
 509  *    If each thread must have global scheduler this must be called in each
 510  *    thread.  If the global scheduler has been set already, new call will
 511  *    replace the old one.
 512  *
 513  *    This routine is provided only as a convenience function to store
 514  *    program's or thread's scheduler in one global place.  It is not mandatory
 515  *    to call this function in order to use SilcSchedule.
 516  *
 517  *    Many routines that require SilcSchedule as an argument will call
 518  *    silc_schedule_get_global if the scheduler is not provided to try to
 519  *    get global scheduler.  Almost all routines in SilcSchedule API will call
 520  *    silc_schedule_get_global if the SilcSchedule is not provided as argument.
 521  *
 522  ***/
 523 void silc_schedule_set_global(SilcSchedule schedule);
 524
 525 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_global
 526  *
 527  * SYNOPSIS
 528  *
 529  *    SilcSchedule silc_schedule_get_global(void);
 530  *
 531  * DESCRIPTION
 532  *
 533  *    Returns the thread's global scheduler that was set by calling
 534  *    silc_schedule_set_global or NULL if global scheduler has not been set.
 535  *
 536  ***/
 537 SilcSchedule silc_schedule_get_global(void);
 538
 539 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_fd
 540  *
 541  * SYNOPSIS
 542  *
 543  *    SilcTask
 544  *    silc_schedule_task_add_fd(SilcSchedule schedule, SilcUInt32 fd,
 545  *                              SilcTaskCallback callback, void *context);
 546  *
 547  * DESCRIPTION
 548  *
 549  *    Add file descriptor task to scheduler.  The `fd' may be either real
 550  *    file descriptor, socket or on some platforms an opaque file descriptor
 551  *    handle.  To receive events for the file descriptor set the correct
 552  *    request events with silc_schedule_set_listen_fd function.
 553  *
 554  *    The task will be initially set for SILC_TASK_READ events.  Setting that
 555  *    event immediately after this call returns is not necessary.
 556  *
 557  *    This returns the new task or NULL on error.  If a task with `fd' has
 558  *    already been added this will return the existing task pointer.
 559  *
 560  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 561  *    get global scheduler.
 562  *
 563  ***/
 564 #define silc_schedule_task_add_fd(schedule, fd, callback, context)      \
 565   silc_schedule_task_add(schedule, fd, callback, context, 0, 0, SILC_TASK_FD)
 566
 567 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_timeout
 568  *
 569  * SYNOPSIS
 570  *
 571  *    SilcTask
 572  *    silc_schedule_task_add_timeout(SilcSchedule schedule,
 573  *                                   SilcTaskCallback callback, void *context,
 574  *                                   long seconds, long useconds);
 575  *
 576  * DESCRIPTION
 577  *
 578  *    Add timeout task to scheduler.  The `callback' will be called once
 579  *    the specified timeout has elapsed.  The task will be removed from the
 580  *    scheduler automatically once the task expires.  The event returned
 581  *    to the `callback' is SILC_TASK_EXPIRE.  A task added with zero (0)
 582  *    timeout will be executed immediately next time tasks are scheduled.
 583  *
 584  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 585  *    get global scheduler.
 586  *
 587  ***/
 588 #define silc_schedule_task_add_timeout(schedule, callback, context, s, u) \
 589   silc_schedule_task_add(schedule, 0, callback, context, s, u,          \
 590                          SILC_TASK_TIMEOUT)
 591
 592 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_signal
 593  *
 594  * SYNOPSIS
 595  *
 596  *    SilcTask
 597  *    silc_schedule_task_add_signal(SilcSchedule schedule, int signal,
 598  *                                  SilcTaskCallback callback, void *context);
 599  *
 600  * DESCRIPTION
 601  *
 602  *    Add platform specific process signal handler to scheduler.  On Unix
 603  *    systems the `signal' is one of the signal specified in signal(7).  On
 604  *    other platforms this function may not be available at all, and has no
 605  *    effect when called.  The event delivered to the `callback' is
 606  *    SILC_TASK_INTERRUPT.
 607  *
 608  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 609  *    get global scheduler.
 610  *
 611  * NOTES
 612  *
 613  *    One signal may be registered only one callback.  Adding second callback
 614  *    for signal that already has one will fail.
 615  *
 616  *    This function always returns NULL.  To remove signal from scheduler by
 617  *    the signal call silc_schedule_task_del_by_fd.
 618  *
 619  ***/
 620 #define silc_schedule_task_add_signal(schedule, sig, callback, context) \
 621   silc_schedule_task_add(schedule, sig, callback, context, 0, 0,        \
 622                          SILC_TASK_SIGNAL)
 623
 624 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_event
 625  *
 626  * SYNOPSIS
 627  *
 628  *    SilcTask
 629  *    silc_schedule_task_add_event(SilcSchedule schedule,
 630  *                                 const char *event, ...);
 631  *
 632  * DESCRIPTION
 633  *
 634  *    Adds an event task to scheduler.  These tasks are asynchronous events
 635  *    that one or more receivers may connect to and receive information or
 636  *    data when the event is signalled.  Event tasks are fast and may be
 637  *    used to efficiently deliver events and data to multiple receivers.  The
 638  *    `event' is the name of the event, and can be used to connect to the
 639  *    event and to signal it.
 640  *
 641  *    The events are global among the `scheduler', its parent scheduler and
 642  *    any of its child schedulers.  It does not matter to which scheduler
 643  *    event is added to, connected to or signalled.  Signal will reach any
 644  *    connected entity, as long as it is the parent or one of the fellow
 645  *    children of `schedule'.
 646  *
 647  *    To connect to an event call silc_schedule_event_connect.
 648  *    To disconnect from event call silc_schedule_event_disconnect.
 649  *    To signal event call silc_schedule_event_signal.
 650  *    To delete event task call silc_schedule_task_del or
 651  *    silc_schedule_task_del_event.
 652  *
 653  *    The variable argument list is used to describe the arguments of the
 654  *    event.  The variable arguments are a list of zero or more SilcParam
 655  *    values.  This function returns the event task context or NULL on error.
 656  *
 657  * EXAMPLE
 658  *
 659  *    // Register 'connected' event
 660  *    silc_schedule_task_add_event(schedule, "connected",
 661  *                                 SILC_PARAM_UINT32,
 662  *                                 SILC_PARAM_BUFFER);
 663  *
 664  *    // Connect to 'connected' event
 665  *    silc_schedule_event_connect(schedule, "connected", NULL,
 666  *                                connected_cb, ctx);
 667  *
 668  *    // Signal 'connected' event
 669  *    silc_schedule_event_signal(schedule, "connected", NULL, integer, buf);
 670  *
 671  *    // 'connected' event handler
 672  *    SILC_TASK_CALLBACK(connected_cb)
 673  *    {
 674  *      FooCtx ctx = context;
 675  *      SilcUInt32 integer;
 676  *      SilcBuffer buf;
 677  *
 678  *      integer = va_arg(va, SilcUInt32);
 679  *      buf = va_arg(va, SilcBuffer);
 680  *      ...
 681  *    }
 682  *
 683  ***/
 684 SilcTask silc_schedule_task_add_event(SilcSchedule schedule,
 685                                       const char *event, ...);
 686
 687 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
 688  *
 689  * SYNOPSIS
 690  *
 691  *    SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
 692  *
 693  * DESCRIPTION
 694  *
 695  *    Deletes the `task' from the scheduler indicated by the `schedule'.
 696  *    After deleting the task it is guaranteed that the task callback
 697  *    will not be called. If the `task' is SILC_ALL_TASKS then all
 698  *    tasks is removed from the scheduler.  Returns always TRUE.
 699  *
 700  *    It is safe to call this function in any place. Tasks may be removed
 701  *    in task callbacks (including in the task's own task callback) and
 702  *    in multi-threaded environment in other threads as well.
 703  *
 704  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 705  *    get global scheduler.
 706  *
 707  ***/
 708 SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
 709
 710 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd
 711  *
 712  * SYNOPSIS
 713  *
 714  *    SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule,
 715  *                                          SilcUInt32 fd);
 716  *
 717  * DESCRIPTION
 718  *
 719  *    Deletes a task from the scheduler by the specified `fd'.  Returns
 720  *    FALSE if such fd task does not exist.
 721  *
 722  *    It is safe to call this function in any place. Tasks may be removed
 723  *    in task callbacks (including in the task's own task callback) and
 724  *    in multi-threaded environment in other threads as well.
 725  *
 726  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 727  *    get global scheduler.
 728  *
 729  ***/
 730 SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
 731
 732 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
 733  *
 734  * SYNOPSIS
 735  *
 736  *    SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
 737  *                                                SilcTaskCallback callback);
 738  *
 739  * DESCRIPTION
 740  *
 741  *    Deletes a task from the scheduler by the specified `callback' task
 742  *    callback function.  Returns FALSE if such task with such callback
 743  *    does not exist.
 744  *
 745  *    It is safe to call this function in any place. Tasks may be removed
 746  *    in task callbacks (including in the task's own task callback) and
 747  *    in multi-threaded environment in other threads as well.
 748  *
 749  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 750  *    get global scheduler.
 751  *
 752  ***/
 753 SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
 754                                             SilcTaskCallback callback);
 755
 756 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context
 757  *
 758  * SYNOPSIS
 759  *
 760  *    SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
 761  *                                               void *context);
 762  *
 763  * DESCRIPTION
 764  *
 765  *    Deletes a task from the scheduler by the specified `context'.  Returns
 766  *    FALSE if such task with such context does not exist.
 767  *
 768  *    It is safe to call this function in any place. Tasks may be removed
 769  *    in task callbacks (including in the task's own task callback) and
 770  *    in multi-threaded environment in other threads as well.
 771  *
 772  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 773  *    get global scheduler.
 774  *
 775  ***/
 776 SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
 777                                            void *context);
 778
 779 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_all
 780  *
 781  * SYNOPSIS
 782  *
 783  *    SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
 784  *                                           SilcTaskCallback callback,
 785  *                                           void *context);
 786  *
 787  * DESCRIPTION
 788  *
 789  *    Deletes a task from the scheduler by the specified `fd', `callback'
 790  *    and `context'.  Returns FALSE if such task does not exist.
 791  *
 792  *    It is safe to call this function in any place. Tasks may be removed
 793  *    in task callbacks (including in the task's own task callback) and
 794  *    in multi-threaded environment in other threads as well.
 795  *
 796  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 797  *    get global scheduler.
 798  *
 799  ***/
 800 SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
 801                                        SilcTaskCallback callback,
 802                                        void *context);
 803
 804 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_event
 805  *
 806  * SYNOPSIS
 807  *
 808  *    void silc_schedule_task_del_event(SilcSchedule schedule,
 809  *                                      const char *event);
 810  *
 811  * DESCRIPTION
 812  *
 813  *    Deletes event task by the event name `event'.  Returns FALSE if the
 814  *    event does not exist.  Events can be deleted by calling the
 815  *    silc_schedule_task_del also.
 816  *
 817  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 818  *    get global scheduler.
 819  *
 820  ***/
 821 SilcBool silc_schedule_task_del_event(SilcSchedule schedule,
 822                                       const char *event);
 823
 824 /****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
 825  *
 826  * SYNOPSIS
 827  *
 828  *    SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule,
 829  *                                         SilcUInt32 fd,
 830  *                                         SilcTaskEvent mask,
 831  *                                         SilcBool send_events);
 832  *
 833  * DESCRIPTION
 834  *
 835  *    Sets a file descriptor `fd' to be listened by the scheduler for
 836  *    `mask' events.  To tell scheduler not to listen anymore for this
 837  *    file descriptor call the silc_schedule_unset_listen_fd function.
 838  *    When new task is created with silc_schedule_task_add the event
 839  *    for the task's fd is initially set to SILC_TASK_READ. If you need
 840  *    to control the task's fd's events you must call this function
 841  *    whenever you need to change the events. This can be called multiple
 842  *    times to change the events.
 843  *
 844  *    If the `send_events' is TRUE then this function sends the events
 845  *    in `mask' to the application.  If FALSE then they are sent only
 846  *    after the event occurs in reality.  In normal cases the `send_events'
 847  *    is set to FALSE.
 848  *
 849  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 850  *    get global scheduler.
 851  *
 852  *    Returns FALSE if the operation could not performed and TRUE if it
 853  *    was a success.
 854  *
 855  ***/
 856 SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
 857                                      SilcTaskEvent mask, SilcBool send_events);
 858
 859 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_fd_events
 860  *
 861  * SYNOPSIS
 862  *
 863  *    SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
 864  *                                              SilcUInt32 fd);
 865  *
 866  * DESCRIPTION
 867  *
 868  *    Returns the file descriptor `fd' current requested events mask,
 869  *    or 0 on error.
 870  *
 871  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 872  *    get global scheduler.
 873  *
 874  ***/
 875 SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
 876                                           SilcUInt32 fd);
 877
 878 /****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
 879  *
 880  * SYNOPSIS
 881  *
 882  *    void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
 883  *
 884  * DESCRIPTION
 885  *
 886  *    Tells the scheduler not to listen anymore for the specified
 887  *    file descriptor `fd'. No events will be detected for the `fd'
 888  *    after calling this function.
 889  *
 890  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 891  *    get global scheduler.
 892  *
 893  ***/
 894 void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
 895
 896 /****f* silcutil/SilcScheduleAPI/silc_schedule_event_connect
 897  *
 898  * SYNOPSIS
 899  *
 900  *    SilcBool silc_schedule_event_connect(SilcSchedule schedule,
 901  *                                         const char *event, SilcTask task,
 902  *                                         SilcTaskEventCallback callback,
 903  *                                         void *context);
 904  *
 905  * DESCRIPTION
 906  *
 907  *    Connects to an event task.  The `event' or `task' must be non-NULL.
 908  *    If `event' is non-NULL it is the name of the event to connect to.  If
 909  *    the `task' is non-NULL it is the event task to connect to.  The event
 910  *    SilcTask pointer is returned by silc_schedule_task_add_event when the
 911  *    even is added to scheduler.
 912  *
 913  *    The `callback' with `context' and with `schedule' are called when the
 914  *    even task is signalled with silc_schedule_event_signal.
 915  *
 916  *    Returns FALSE on error or if the `callback' with `context' has already
 917  *    been connected.  Otherwise, returns TRUE.
 918  *
 919  * EXAMPLE
 920  *
 921  *    silc_schedule_event_connect(schedule, "foo event", NULL,
 922  *                                foo_signal_callback, foo_context);
 923  *
 924  ***/
 925 SilcBool silc_schedule_event_connect(SilcSchedule schedule,
 926                                      const char *event, SilcTask task,
 927                                      SilcTaskEventCallback callback,
 928                                      void *context);
 929
 930 /****f* silcutil/SilcScheduleAPI/silc_schedule_event_disconnect
 931  *
 932  * SYNOPSIS
 933  *
 934  *    SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
 935  *                                            const char *event, SilcTask task,
 936  *                                            SilcTaskEventCallback callback,
 937  *                                            void *context);
 938  *
 939  * DESCRIPTION
 940  *
 941  *    Disconnects the `callback' and `context' from an event task.  The `event'
 942  *    or `task' must be non-NULL.  If `event' is non-NULL it is the name of
 943  *    the event.  If `task' is non-NULL it is the event task.
 944  *
 945  *    Returns FALSE on error or if the `callback' with `context' has not been
 946  *    connected.  Otherwise, returns TRUE.
 947  *
 948  * EXAMPLE
 949  *
 950  *    silc_schedule_event_connect(schedule, "foo event", NULL,
 951  *                                foo_signal_callback, foo_context);
 952  *
 953  ***/
 954 SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
 955                                         const char *event, SilcTask task,
 956                                         SilcTaskEventCallback callback,
 957                                         void *context);
 958
 959 /****f* silcutil/SilcScheduleAPI/silc_schedule_event_signal
 960  *
 961  * SYNOPSIS
 962  *
 963  *    SilcBool silc_schedule_event_signal(SilcSchedule schedule,
 964  *                                        const char *event,
 965  *                                        SilcTask task, ...);
 966  *
 967  * DESCRIPTION
 968  *
 969  *    Signals an event task.  The `event' or `task' must be non-NULL.  If
 970  *    `event' is non-NULL it is the name of the event to signal.  If the `task'
 971  *    is non-NULL it is the task to be signalled.  It is marginally faster
 972  *    to use the `task' pointer directly instead of `event' to send the signal.
 973  *
 974  *    The variable arguments are the arguments to be sent in the signal to
 975  *    the connected entities.  The silc_schedule_task_add_event defines what
 976  *    arguments must be sent to each signal.
 977  *
 978  *    Signal delivery is synchronous; the signal is delivered inside this
 979  *    function.  If a receiver was originally in another thread, the signal
 980  *    is delivered in the thread where this function is called.  This means
 981  *    that concurrency control (locking) is required if the application uses
 982  *    events in multiple threads.
 983  *
 984  * EXAMPLE
 985  *
 986  *    silc_schedule_event_signal(schedule, "foo event", NULL, intarg, buffer);
 987  *
 988  ***/
 989 SilcBool silc_schedule_event_signal(SilcSchedule schedule, const char *event,
 990                                     SilcTask task, ...);
 991
 992 #endif