lib/silcutil/silcschedule.h

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