X-Git-Url: http://git.silcnet.org/gitweb/?p=crypto.git;a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcschedule.h;h=c37ecc6690dad71c522a4a29697ee2dbe5e8c7ae;hp=19c384684e35f8c52b0f53f210b9a33794e98a5f;hb=60180da59ffdbbd12058dded66e3c8a547cd0852;hpb=89b07a460a554eb5173fe07f09b8c51c31d53e29

diff --git a/lib/silcutil/silcschedule.h b/lib/silcutil/silcschedule.h
index 19c38468..c37ecc66 100644
--- a/lib/silcutil/silcschedule.h
+++ b/lib/silcutil/silcschedule.h
@@ -2,15 +2,14 @@
 
   silcschedule.h
 
-  Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+  Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 1998 - 2000 Pekka Riikonen
+  Copyright (C) 1998 - 2007 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
-  (at your option) any later version.
-  
+  the Free Software Foundation; version 2 of the License.
+
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@@ -18,106 +17,976 @@
 
 */
 
+/****h* silcutil/SILC Schedule Interface
+ *
+ * DESCRIPTION
+ *
+ * The SILC Scheduler is the heart of any application. The scheduler provides
+ * the application's main loop that can handle incoming data, outgoing data,
+ * timeouts and dispatch different kind of tasks.
+ *
+ * The SILC Scheduler supports file descriptor based tasks and timeout tasks.
+ * File descriptor tasks are tasks that perform some operation over the
+ * specified file descriptor. These include network connections, for example.
+ * The timeout tasks are timeouts that are executed after the specified
+ * timeout has elapsed.
+ *
+ * The SILC Scheduler is designed to be the sole main loop of the application
+ * so that the application does not need any other main loop.  However,
+ * SILC Scheduler does support running the scheduler only once, so that the
+ * scheduler does not block, and thus providing a possiblity that some
+ * external main loop is run over the SILC Scheduler.
+ *
+ * Typical application first initializes the scheduler and then registers
+ * the very first tasks to the scheduler and then run the scheduler.  After
+ * the scheduler's run function returns the application is considered to be
+ * ended.
+ *
+ * On WIN32 systems the SILC Scheduler is too designed to work as the main
+ * loop of the GUI application. It can handle all Windows messages and
+ * it dispatches them from the scheduler, and thus makes it possible to
+ * create GUI applications. The scheduler can also handle all kinds of
+ * WIN32 handles, this includes sockets created by the SILC Net API routines,
+ * WSAEVENT handle objects created by Winsock2 routines and arbitrary
+ * WIN32 HANDLE objects.
+ *
+ * The SILC Scheduler supports multi-threads as well. The actual scheduler
+ * must be run in single-thread but other threads may register new tasks
+ * and unregister old tasks.  However, it is enforced that the actual
+ * task is always run in the main thread.  The scheduler is context based
+ * which makes it possible to allocate several schedulers for one application.
+ * Since the scheduler must be run in single-thread, a multi-threaded
+ * application could be created by allocating own scheduler for each of the
+ * worker threads.
+ *
+ ***/
+
 #ifndef SILCSCHEDULE_H
 #define SILCSCHEDULE_H
 
-/* Structure holding list of file descriptors, scheduler is supposed to
-   be listenning. The max_fd field is the maximum number of possible file
-   descriptors in the list. This value is set at the initialization
-   of the scheduler and it usually is the maximum number of connections 
-   allowed. */
-typedef struct {
-  int *fd;
-  unsigned int last_fd;
-  unsigned int max_fd;
-} SilcScheduleFdList;
+/****s* silcutil/SilcScheduleAPI/SilcSchedule
+ *
+ * NAME
+ *
+ *    typedef struct SilcScheduleStruct *SilcSchedule;
+ *
+ * DESCRIPTION
+ *
+ *    This context is the actual Scheduler and is allocated by
+ *    the silc_schedule_init funtion.  The context is given as argument
+ *    to all silc_schedule_* functions.  It must be freed by the
+ *    silc_schedule_uninit function.
+ *
+ ***/
+typedef struct SilcScheduleStruct *SilcSchedule;
+
+/****s* silcutil/SilcScheduleAPI/SilcTask
+ *
+ * NAME
+ *
+ *    typedef struct SilcTaskStruct *SilcTask;
+ *
+ * DESCRIPTION
+ *
+ *    This object represents one task in the scheduler.  It is allocated
+ *    by the silc_schedule_task_add function and freed by one of the
+ *    silc_schedule_task_del* functions.
+ *
+ ***/
+typedef struct SilcTaskStruct *SilcTask;
 
-/* 
-   Silc Schedule object. 
+/****d* silcutil/SilcScheduleAPI/SilcTaskEvent
+ *
+ * NAME
+ *
+ *    typedef enum { ... } SilcTaskEvent;
+ *
+ * DESCRIPTION
+ *
+ *    SILC Task event types.  The event type indicates the occurred
+ *    event of the task.  This type will be given as argument to the
+ *    SilcTaskCallback function to indicate the event for the caller.
+ *    The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller
+ *    of the silc_schedule_set_listen_fd, if the caller needs to control
+ *    the events for the task. The SILC_TASK_EXPIRE is set always only
+ *    by the scheduler when timeout expires for timeout task.  The
+ *    SILC_TASK_INTERRUPT is set for signal callback.
+ *
+ * SOURCE
+ */
+typedef enum {
+  SILC_TASK_READ         = 0x0001,	         /* Reading */
+  SILC_TASK_WRITE        = 0x0002,		 /* Writing */
+  SILC_TASK_EXPIRE       = 0x0004,		 /* Timeout */
+  SILC_TASK_INTERRUPT    = 0x0008,		 /* Signal */
+} SilcTaskEvent;
+/***/
 
-   This is the actual schedule object in Silc. Both Silc client and server 
-   uses this same scheduler. Actually, this scheduler could be used by any
-   program needing scheduling.
+/****f* silcutil/SilcScheduleAPI/SilcTaskCallback
+ *
+ * SYNOPSIS
+ *
+ *    typedef void (*SilcTaskCallback)(SilcSchedule schedule,
+ *                                     void *app_context,
+ *                                     SilcTaskEvent type, SilcUInt32 fd,
+ *                                     void *context);
+ *
+ * DESCRIPTION
+ *
+ *    The task callback function.  This function will be called by the
+ *    scheduler when some event of the task is performed.  For example,
+ *    when data is available from the connection this will be called.
+ *
+ *    The `schedule' is the scheduler context, the `type' is the indicated
+ *    event, the `fd' is the file descriptor of the task and the `context'
+ *    is a caller specified context. If multiple events occurred this
+ *    callback is called separately for all events.  The `app_context'
+ *    is application specific context that was given as argument to the
+ *    silc_schedule_init function.  If the task is timeout task then `fd'
+ *    is zero (0).
+ *
+ *    To specify task callback function in the application using the
+ *    SILC_TASK_CALLBACK macro is recommended.
+ *
+ *    The callback should not perform lenghty or blocking operations as
+ *    this would also block all other waiting tasks.  The task callback
+ *    should either handle the operation fast or issue an asynchronous
+ *    call (like to register 0 timeout task) to handle it later.
+ *
+ ***/
+typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context,
+				 SilcTaskEvent type, SilcUInt32 fd,
+				 void *context);
 
-   Following short description of the fields:
+/****f* silcutil/SilcScheduleAPI/SilcTaskEventCallback
+ *
+ * SYNOPSIS
+ *
+ *    typedef void (*SilcTaskEventCallback)(SilcSchedule schedule,
+ *                                          void *app_context,
+ *                                          SilcTask task, void *context,
+ *                                          va_list va);
+ *
+ * DESCRIPTION
+ *
+ *    Task callback for event tasks added with silc_schedule_task_add_event.
+ *    The callback of this type is called when an event task is signalled.
+ *    The signal is delivered to all that have connected to the event.
+ *
+ *    The `task' is the event task.  The `context' is the context given as
+ *    argument to silc_schedule_event_connect.  The `schedule' is the
+ *    scheduler given as argument to silc_schedule_event_connect.
+ *
+ *    If FALSE is returned in this callback function the signal delivery to
+ *    other connected entities is stopped.  Normally, TRUE is returned.
+ *    If the `task' is deleted in this callback, the signal delivery is also
+ *    stopped.
+ *
+ *    To specify task event callback function in the application using the
+ *    SILC_TASK_EVENT_CALLBACK macro is recommended.
+ *
+ ***/
+typedef SilcBool (*SilcTaskEventCallback)(SilcSchedule schedule,
+					  void *app_context,
+					  SilcTask task, void *context,
+					  va_list va);
 
-   SilcTaskQueue fd_queue
+/****f* silcutil/SilcScheduleAPI/SilcTaskNotifyCb
+ *
+ * SYNOPSIS
+ *
+ *    typedef void (*SilcTaskNotifyCb)(SilcSchedule schedule,
+ *                                     SilcBool added, SilcTask task,
+ *                                     SilcBool fd_task, SilcUInt32 fd,
+ *                                     SilcTaskEvent event,
+ *                                     long seconds, long useconds,
+ *                                     void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Task notify callback.  Callback of this type can be set to scheduler
+ *    by calling silc_schedule_set_notify and will be called whenever new
+ *    task is added or old task is removed.  If `added' is TRUE then `task'
+ *    is added to scheduler.  If `added' is FALSE then `task' will be removed
+ *    from the scheduler.  If `fd_task' is TRUE the `task' is file descriptor
+ *    task and has `fd' is its file descriptor.  If `fd_task' is FALSE then
+ *    the task is timeout task and `seconds' and `useconds' specify the
+ *    timeout.  The `context' is the context given to silc_schedule_set_notify.
+ *
+ * NOTES
+ *
+ *    The `schedule' is locked while this callback is called.  This means that
+ *    new tasks cannot be added or removed inside this callback.
+ *
+ *    When timeout task expires this callback is not called.  This is called
+ *    only when task is explicitly deleted from the scheduler.  Note that,
+ *    when timeout task expires it is removed from the scheduler and `task'
+ *    will become invalid.
+ *
+ *    If fd task changes its events, this will be called as if it was a new
+ *    task with different `event' mask.
+ *
+ ***/
+typedef void (*SilcTaskNotifyCb)(SilcSchedule schedule,
+				 SilcBool added, SilcTask task,
+				 SilcBool fd_task, SilcUInt32 fd,
+				 SilcTaskEvent event,
+				 long seconds, long useconds,
+				 void *app_context);
 
-       Task queue hook for non-timeout tasks. Usually this means that these
-       tasks perform different kind of I/O on file descriptors. File 
-       descriptors are usually network sockets but they actually can be
-       any file descriptors. This hook is initialized in silc_schedule_init
-       function. Timeout tasks should not be added to this queue because
-       they will never expire.
+/* Macros */
 
-   SilcTaskQueue timeout_queue
+/****d* silcutil/SilcScheduleAPI/SILC_ALL_TASKS
+ *
+ * NAME
+ *
+ *    #define SILC_ALL_TASKS ...
+ *
+ * DESCRIPTION
+ *
+ *    Marks for all tasks in the scheduler. This can be passed to
+ *    silc_schedule_task_del function to delete all tasks at once.
+ *
+ * SOURCE
+ */
+#define SILC_ALL_TASKS ((SilcTask)1)
+/***/
 
-       Task queue hook for timeout tasks. This hook is reserved specificly
-       for tasks with timeout. Non-timeout tasks should not be added to this
-       queue because they will never get scheduled. This hook is also
-       initialized in silc_schedule_init function.
+/****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
+ *
+ * NAME
+ *
+ *    #define SILC_TASK_CALLBACK ...
+ *
+ * DESCRIPTION
+ *
+ *    Generic macro to declare task callback functions. This defines a
+ *    function with name `func' as a task callback function.
+ *
+ * SOURCE
+ */
+#define SILC_TASK_CALLBACK(func)					\
+void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type,	\
+	  SilcUInt32 fd, void *context)
+/***/
 
-   SilcTaskQueue generic_queue
+/****d* silcutil/SilcScheduleAPI/SILC_TASK_EVENT_CALLBACK
+ *
+ * NAME
+ *
+ *    #define SILC_TASK_EVENT_CALLBACK ...
+ *
+ * DESCRIPTION
+ *
+ *    Generic macro to declare event task callback functions. This defines a
+ *    function with name `func' as a event task callback function.
+ *
+ * SOURCE
+ */
+#define SILC_TASK_EVENT_CALLBACK(func)					\
+SilcBool func(SilcSchedule schedule, void *app_context,			\
+	      SilcTask task, void *context, va_list va)
 
-       Task queue hook for generic tasks. This hook is reserved specificly
-       for generic tasks, tasks that apply to all file descriptors, except
-       to those that have specificly registered a non-timeout task. This hook
-       is also initialized in silc_schedule_init function.
+/***/
 
-   SilcScheduleFdList fd_list
+/* Prototypes */
 
-       List of file descriptors the scheduler is supposed to be listenning.
-       This is updated internally.
+#include "silcschedule_i.h"
 
-   struct timeval *timeout;
+/****f* silcutil/SilcScheduleAPI/silc_schedule_init
+ *
+ * SYNOPSIS
+ *
+ *    SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
+ *                                    SilcStack stack, SilcSchedule parent);
+ *
+ * DESCRIPTION
+ *
+ *    Initializes the scheduler. This returns the scheduler context or NULL
+ *    on error.  The `app_context' is application specific context that is
+ *    delivered to all task callbacks. The caller must free that context.
+ *
+ *    The `max_tasks' is the maximum number of file descriptor and socket
+ *    tasks in the scheduler.  Set value to 0 to use default.  Operating
+ *    system will enforce the final limit.  On some operating systems the
+ *    limit can be significantly increased when this function is called in
+ *    priviliged mode (as super user).
+ *
+ *    If `parent' is non-NULL it will be the parent of the new scheduler.
+ *    If it is NULL this will create a new parent scheduler.  If `parent'
+ *    is already a child scheduler, this will create a new child to the
+ *    child's parent.  Even if `parent' is non-NULL the new child scheduler
+ *    is still independent scheduler and will run independently of its
+ *    parent.  However, each child and parent will share event tasks
+ *    added with silc_schedule_task_add_event.
+ *
+ *    If `stack' is non-NULL all memory allocation for the scheduler is done
+ *    from the `stack'.  Scheduler's stack may be retrieved by calling
+ *    silc_schedule_get_stack.  A stack is created for scheduler always even
+ *    if `stack' is NULL.  If it is non-NULL the created stack is a child
+ *    stack using `stack' as its parent.  This means that memory allocated
+ *    by the scheduler will be returned to the `stack' when scheduler is
+ *    destroyed.
+ *
+ ***/
+SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
+				SilcStack stack, SilcSchedule parent);
 
-       Pointer to the schedules next timeout. Value of this timeout is
-       automatically updated in the silc_schedule function.
+/****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_uninit(SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ *    Uninitializes the scheduler. This is called when the program is ready
+ *    to end. This removes all tasks from the scheduler. Returns FALSE if the
+ *    scheduler could not be uninitialized. This happens when the scheduler
+ *    is still valid and silc_schedule_stop has not been called.
+ *
+ *    If SilcStack was given to silc_schedule_init all memory allocated
+ *    during the life time of the scheduler will be returned back to the
+ *    given stack.
+ *
+ ***/
+SilcBool silc_schedule_uninit(SilcSchedule schedule);
 
-   int valid
+/****f* silcutil/SilcScheduleAPI/silc_schedule_stop
+ *
+ * SYNOPSIS
+ *
+ *    void silc_schedule_stop(SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ *    Stops the scheduler even if it is not supposed to be stopped yet.
+ *    After calling this, one must call silc_schedule_uninit (after the
+ *    silc_schedule has returned).  After this is called it is guaranteed
+ *    that next time the scheduler enters the main loop it will be stopped.
+ *    However, untill it enters the main loop it will not detect that
+ *    it is stopped for example if this is called from another thread.
+ *
+ ***/
+void silc_schedule_stop(SilcSchedule schedule);
 
-       Marks validity of the scheduler. This is a boolean value. When this
-       is false the scheduler is terminated and the program will end. This
-       set to true when the scheduler is initialized with silc_schedule_init
-       function.
+/****f* silcutil/SilcScheduleAPI/silc_schedule
+ *
+ * SYNOPSIS
+ *
+ *    void silc_schedule(SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ *    The SILC scheduler.  The program will run inside this function.
+ *    When this returns the program is to be ended.  Before this function
+ *    can be called, one must call silc_schedule_init function.
+ *
+ * NOTES
+ *
+ *    On Windows this will block the calling thread but will continue
+ *    to dispatch window messages, and thus can be used as the main loop
+ *    of the program.
+ *
+ *    On Symbian this will block the calling thread.  The Symbian Active
+ *    Scheduler must be running before calling this function.
+ *
+ ***/
+void silc_schedule(SilcSchedule schedule);
 
-   fd_set in
-   fd_set out
+/****f* silcutil/SilcScheduleAPI/silc_schedule_one
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
+ *
+ * DESCRIPTION
+ *
+ *    Same as the silc_schedule but runs the scheduler only one round
+ *    and then returns.  This function is handy when the SILC scheduler
+ *    is used inside some other external scheduler, for example.  If
+ *    the `timeout_usecs' is non-negative a timeout will be added to the
+ *    scheduler.  The function will not return in this timeout unless
+ *    some other event occurs.
+ *
+ *    Typically this would be called from a timeout or idle task
+ *    periodically (typically from 5-50 ms) to schedule SILC tasks.  In
+ *    this case the `timeout_usecs' is usually 0 to make the function
+ *    return immediately.
+ *
+ ***/
+SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
 
-       File descriptor sets for select(). These are automatically managed
-       by the scheduler and should not be touched otherwise.
+/****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup
+ *
+ * SYNOPSIS
+ *
+ *    void silc_schedule_wakeup(SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ *    Wakes up the scheduler. This is may be used in multi-threaded
+ *    environments where threads may add new tasks or remove old tasks
+ *    from the scheduler. This is called to wake up the scheduler in the
+ *    main thread so that it detects the changes in the scheduler.
+ *    If threads support is not compiled in this function has no effect.
+ *
+ ***/
+void silc_schedule_wakeup(SilcSchedule schedule);
 
-   int max_fd
+/****f* silcutil/SilcScheduleAPI/silc_schedule_get_parent
+ *
+ * SYNOPSIS
+ *
+ *    SilcSchedule silc_schedule_get_parent(SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the parent scheduler of the `schedule'.  Never returns NULL.
+ *
+ ***/
+SilcSchedule silc_schedule_get_parent(SilcSchedule schedule);
 
-       Number of maximum file descriptors for select(). This, as well, is
-       managed automatically by the scheduler and should be considered to 
-       be read-only field otherwise.
+/****f* silcutil/SilcScheduleAPI/silc_schedule_get_context
+ *
+ * SYNOPSIS
+ *
+ *    void *silc_schedule_get_context(SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the application specific context that was saved into the
+ *    scheduler in silc_schedule_init function.  The context is also
+ *    returned to application in the SilcTaskCallback, but this function
+ *    may be used to get it as well if needed.
+ *
+ ***/
+void *silc_schedule_get_context(SilcSchedule schedule);
 
-*/
+/****f* silcutil/SilcScheduleAPI/silc_schedule_get_stack
+ *
+ * SYNOPSIS
+ *
+ *    SilcStack silc_schedule_get_stack(SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the stack of the `schedule'.  If it is used to make memory
+ *    allocations outside the scheduler, it is recommended that a new
+ *    child stack is created by using the returned stack as a parent and
+ *    using the child stack to make the memory allocations.
+ *
+ ***/
+SilcStack silc_schedule_get_stack(SilcSchedule schedule);
 
-typedef struct {
-  SilcTaskQueue fd_queue;
-  SilcTaskQueue timeout_queue;
-  SilcTaskQueue generic_queue;
-  SilcScheduleFdList fd_list;
-  struct timeval *timeout;
-  int valid;
-  fd_set in;
-  fd_set out;
-  int max_fd;
-} SilcScheduleObject;
+/****f* silcutil/SilcScheduleAPI/silc_schedule_set_notify
+ *
+ * SYNOPSIS
+ *
+ *    void silc_schedule_set_notify(SilcSchedule schedule,
+ *                                  SilcTaskNotifyCb notify, void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Set notify callback to scheduler.  The `notify' will be called whenever
+ *    task is added to or deleted from scheduler.
+ *
+ ***/
+void silc_schedule_set_notify(SilcSchedule schedule,
+			      SilcTaskNotifyCb notify, void *context);
 
-typedef SilcScheduleObject SilcSchedule;
+/****f* silcutil/SilcScheduleAPI/silc_schedule_set_global
+ *
+ * SYNOPSIS
+ *
+ *    void silc_schedule_set_global(SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ *    Sets global SilcSchedule `schedule' that can be retrieved at any time
+ *    by using silc_schedule_get_global.  The global scheduler is global only
+ *    to the current thread.  Each thread can have their own global scheduler.
+ *    If each thread must have global scheduler this must be called in each
+ *    thread.  If the global scheduler has been set already, new call will
+ *    replace the old one.
+ *
+ *    This routine is provided only as a convenience function to store
+ *    program's or thread's scheduler in one global place.  It is not mandatory
+ *    to call this function in order to use SilcSchedule.
+ *
+ *    Many routines that require SilcSchedule as an argument will call
+ *    silc_schedule_get_global if the scheduler is not provided to try to
+ *    get global scheduler.  Almost all routines in SilcSchedule API will call
+ *    silc_schedule_get_global if the SilcSchedule is not provided as argument.
+ *
+ ***/
+void silc_schedule_set_global(SilcSchedule schedule);
 
-/* Prototypes */
-void silc_schedule_init(SilcTaskQueue *fd_queue,
-			SilcTaskQueue *timeout_queue,
-			SilcTaskQueue *generic_queue,
-			int max_fd);
-int silc_schedule_uninit();
-void silc_schedule_stop();
-void silc_schedule_set_listen_fd(int fd, unsigned int iomask);
-void silc_schedule_unset_listen_fd(int fd);
-void silc_schedule();
+/****f* silcutil/SilcScheduleAPI/silc_schedule_get_global
+ *
+ * SYNOPSIS
+ *
+ *    SilcSchedule silc_schedule_get_global(void);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the thread's global scheduler that was set by calling
+ *    silc_schedule_set_global or NULL if global scheduler has not been set.
+ *
+ ***/
+SilcSchedule silc_schedule_get_global(void);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_fd
+ *
+ * SYNOPSIS
+ *
+ *    SilcTask
+ *    silc_schedule_task_add_fd(SilcSchedule schedule, SilcUInt32 fd,
+ *                              SilcTaskCallback callback, void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Add file descriptor task to scheduler.  The `fd' may be either real
+ *    file descriptor, socket or on some platforms an opaque file descriptor
+ *    handle.  To receive events for the file descriptor set the correct
+ *    request events with silc_schedule_set_listen_fd function.
+ *
+ *    The task will be initially set for SILC_TASK_READ events.  Setting that
+ *    event immediately after this call returns is not necessary.
+ *
+ *    This returns the new task or NULL on error.  If a task with `fd' has
+ *    already been added this will return the existing task pointer.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+#define silc_schedule_task_add_fd(schedule, fd, callback, context)	\
+  silc_schedule_task_add(schedule, fd, callback, context, 0, 0,	SILC_TASK_FD)
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_timeout
+ *
+ * SYNOPSIS
+ *
+ *    SilcTask
+ *    silc_schedule_task_add_timeout(SilcSchedule schedule,
+ *                                   SilcTaskCallback callback, void *context,
+ *                                   long seconds, long useconds);
+ *
+ * DESCRIPTION
+ *
+ *    Add timeout task to scheduler.  The `callback' will be called once
+ *    the specified timeout has elapsed.  The task will be removed from the
+ *    scheduler automatically once the task expires.  The event returned
+ *    to the `callback' is SILC_TASK_EXPIRE.  A task added with zero (0)
+ *    timeout will be executed immediately next time tasks are scheduled.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+#define silc_schedule_task_add_timeout(schedule, callback, context, s, u) \
+  silc_schedule_task_add(schedule, 0, callback, context, s, u,		\
+                         SILC_TASK_TIMEOUT)
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_signal
+ *
+ * SYNOPSIS
+ *
+ *    SilcTask
+ *    silc_schedule_task_add_signal(SilcSchedule schedule, int signal,
+ *                                  SilcTaskCallback callback, void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Add platform specific process signal handler to scheduler.  On Unix
+ *    systems the `signal' is one of the signal specified in signal(7).  On
+ *    other platforms this function may not be available at all, and has no
+ *    effect when called.  The event delivered to the `callback' is
+ *    SILC_TASK_INTERRUPT.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ * NOTES
+ *
+ *    One signal may be registered only one callback.  Adding second callback
+ *    for signal that already has one will fail.
+ *
+ *    This function always returns NULL.  To remove signal from scheduler by
+ *    the signal call silc_schedule_task_del_by_fd.
+ *
+ ***/
+#define silc_schedule_task_add_signal(schedule, sig, callback, context) \
+  silc_schedule_task_add(schedule, sig, callback, context, 0, 0,	\
+			 SILC_TASK_SIGNAL)
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_event
+ *
+ * SYNOPSIS
+ *
+ *    SilcTask
+ *    silc_schedule_task_add_event(SilcSchedule schedule,
+ *                                 const char *event, ...);
+ *
+ * DESCRIPTION
+ *
+ *    Adds an event task to scheduler.  These tasks are asynchronous events
+ *    that one or more receivers may connect to and receive information or
+ *    data when the event is signalled.  Event tasks are fast and may be
+ *    used to efficiently deliver events and data to multiple receivers.  The
+ *    `event' is the name of the event, and can be used to connect to the
+ *    event and to signal it.
+ *
+ *    The events are global among the `scheduler', its parent scheduler and
+ *    any of its child schedulers.  It does not matter to which scheduler
+ *    event is added to, connected to or signalled.  Signal will reach any
+ *    connected entity, as long as it is the parent or one of the fellow
+ *    children of `schedule'.
+ *
+ *    To connect to an event call silc_schedule_event_connect.
+ *    To disconnect from event call silc_schedule_event_disconnect.
+ *    To signal event call silc_schedule_event_signal.
+ *    To delete event task call silc_schedule_task_del or
+ *    silc_schedule_task_del_event.
+ *
+ *    The variable argument list is used to describe the arguments of the
+ *    event.  The variable arguments are a list of zero or more SilcParam
+ *    values.  This function returns the event task context or NULL on error.
+ *
+ * EXAMPLE
+ *
+ *    // Register 'connected' event
+ *    silc_schedule_task_add_event(schedule, "connected",
+ *                                 SILC_PARAM_UINT32,
+ *                                 SILC_PARAM_BUFFER);
+ *
+ *    // Connect to 'connected' event
+ *    silc_schedule_event_connect(schedule, "connected", NULL,
+ *                                connected_cb, ctx);
+ *
+ *    // Signal 'connected' event
+ *    silc_schedule_event_signal(schedule, "connected", NULL, integer, buf);
+ *
+ *    // 'connected' event handler
+ *    SILC_TASK_CALLBACK(connected_cb)
+ *    {
+ *      FooCtx ctx = context;
+ *      SilcUInt32 integer;
+ *      SilcBuffer buf;
+ *
+ *      integer = va_arg(va, SilcUInt32);
+ *      buf = va_arg(va, SilcBuffer);
+ *      ...
+ *    }
+ *
+ ***/
+SilcTask silc_schedule_task_add_event(SilcSchedule schedule,
+				      const char *event, ...);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
+ *
+ * DESCRIPTION
+ *
+ *    Deletes the `task' from the scheduler indicated by the `schedule'.
+ *    After deleting the task it is guaranteed that the task callback
+ *    will not be called. If the `task' is SILC_ALL_TASKS then all
+ *    tasks is removed from the scheduler.  Returns always TRUE.
+ *
+ *    It is safe to call this function in any place. Tasks may be removed
+ *    in task callbacks (including in the task's own task callback) and
+ *    in multi-threaded environment in other threads as well.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule,
+ *                                          SilcUInt32 fd);
+ *
+ * DESCRIPTION
+ *
+ *    Deletes a task from the scheduler by the specified `fd'.  Returns
+ *    FALSE if such fd task does not exist.
+ *
+ *    It is safe to call this function in any place. Tasks may be removed
+ *    in task callbacks (including in the task's own task callback) and
+ *    in multi-threaded environment in other threads as well.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
+ *                                                SilcTaskCallback callback);
+ *
+ * DESCRIPTION
+ *
+ *    Deletes a task from the scheduler by the specified `callback' task
+ *    callback function.  Returns FALSE if such task with such callback
+ *    does not exist.
+ *
+ *    It is safe to call this function in any place. Tasks may be removed
+ *    in task callbacks (including in the task's own task callback) and
+ *    in multi-threaded environment in other threads as well.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
+					    SilcTaskCallback callback);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
+ *                                               void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Deletes a task from the scheduler by the specified `context'.  Returns
+ *    FALSE if such task with such context does not exist.
+ *
+ *    It is safe to call this function in any place. Tasks may be removed
+ *    in task callbacks (including in the task's own task callback) and
+ *    in multi-threaded environment in other threads as well.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
+					   void *context);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_all
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
+ *                                           SilcTaskCallback callback,
+ *                                           void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Deletes a task from the scheduler by the specified `fd', `callback'
+ *    and `context'.  Returns FALSE if such task does not exist.
+ *
+ *    It is safe to call this function in any place. Tasks may be removed
+ *    in task callbacks (including in the task's own task callback) and
+ *    in multi-threaded environment in other threads as well.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
+				       SilcTaskCallback callback,
+				       void *context);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_event
+ *
+ * SYNOPSIS
+ *
+ *    void silc_schedule_task_del_event(SilcSchedule schedule,
+ *                                      const char *event);
+ *
+ * DESCRIPTION
+ *
+ *    Deletes event task by the event name `event'.  Returns FALSE if the
+ *    event does not exist.  Events can be deleted by calling the
+ *    silc_schedule_task_del also.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+SilcBool silc_schedule_task_del_event(SilcSchedule schedule,
+				      const char *event);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule,
+ *                                         SilcUInt32 fd,
+ *                                         SilcTaskEvent mask,
+ *                                         SilcBool send_events);
+ *
+ * DESCRIPTION
+ *
+ *    Sets a file descriptor `fd' to be listened by the scheduler for
+ *    `mask' events.  To tell scheduler not to listen anymore for this
+ *    file descriptor call the silc_schedule_unset_listen_fd function.
+ *    When new task is created with silc_schedule_task_add the event
+ *    for the task's fd is initially set to SILC_TASK_READ. If you need
+ *    to control the task's fd's events you must call this function
+ *    whenever you need to change the events. This can be called multiple
+ *    times to change the events.
+ *
+ *    If the `send_events' is TRUE then this function sends the events
+ *    in `mask' to the application.  If FALSE then they are sent only
+ *    after the event occurs in reality.  In normal cases the `send_events'
+ *    is set to FALSE.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ *    Returns FALSE if the operation could not performed and TRUE if it
+ *    was a success.
+ *
+ ***/
+SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
+				     SilcTaskEvent mask, SilcBool send_events);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_get_fd_events
+ *
+ * SYNOPSIS
+ *
+ *    SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
+ *                                              SilcUInt32 fd);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the file descriptor `fd' current requested events mask,
+ *    or 0 on error.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
+					  SilcUInt32 fd);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
+ *
+ * SYNOPSIS
+ *
+ *    void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
+ *
+ * DESCRIPTION
+ *
+ *    Tells the scheduler not to listen anymore for the specified
+ *    file descriptor `fd'. No events will be detected for the `fd'
+ *    after calling this function.
+ *
+ *    If `schedule' is NULL this will call silc_schedule_get_global to try to
+ *    get global scheduler.
+ *
+ ***/
+void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_event_connect
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_event_connect(SilcSchedule schedule,
+ *                                         const char *event, SilcTask task,
+ *                                         SilcTaskEventCallback callback,
+ *                                         void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Connects to an event task.  The `event' or `task' must be non-NULL.
+ *    If `event' is non-NULL it is the name of the event to connect to.  If
+ *    the `task' is non-NULL it is the event task to connect to.  The event
+ *    SilcTask pointer is returned by silc_schedule_task_add_event when the
+ *    even is added to scheduler.
+ *
+ *    The `callback' with `context' and with `schedule' are called when the
+ *    even task is signalled with silc_schedule_event_signal.
+ *
+ *    Returns FALSE on error or if the `callback' with `context' has already
+ *    been connected.  Otherwise, returns TRUE.
+ *
+ * EXAMPLE
+ *
+ *    silc_schedule_event_connect(schedule, "foo event", NULL,
+ *                                foo_signal_callback, foo_context);
+ *
+ ***/
+SilcBool silc_schedule_event_connect(SilcSchedule schedule,
+				     const char *event, SilcTask task,
+				     SilcTaskEventCallback callback,
+				     void *context);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_event_disconnect
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
+ *                                            const char *event, SilcTask task,
+ *                                            SilcTaskEventCallback callback,
+ *                                            void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Disconnects the `callback' and `context' from an event task.  The `event'
+ *    or `task' must be non-NULL.  If `event' is non-NULL it is the name of
+ *    the event.  If `task' is non-NULL it is the event task.
+ *
+ *    Returns FALSE on error or if the `callback' with `context' has not been
+ *    connected.  Otherwise, returns TRUE.
+ *
+ * EXAMPLE
+ *
+ *    silc_schedule_event_connect(schedule, "foo event", NULL,
+ *                                foo_signal_callback, foo_context);
+ *
+ ***/
+SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
+					const char *event, SilcTask task,
+					SilcTaskEventCallback callback,
+					void *context);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_event_signal
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_schedule_event_signal(SilcSchedule schedule,
+ *                                        const char *event,
+ *                                        SilcTask task, ...);
+ *
+ * DESCRIPTION
+ *
+ *    Signals an event task.  The `event' or `task' must be non-NULL.  If
+ *    `event' is non-NULL it is the name of the event to signal.  If the `task'
+ *    is non-NULL it is the task to be signalled.  It is marginally faster
+ *    to use the `task' pointer directly instead of `event' to send the signal.
+ *
+ *    The variable arguments are the arguments to be sent in the signal to
+ *    the connected entities.  The silc_schedule_task_add_event defines what
+ *    arguments must be sent to each signal.
+ *
+ *    Signal delivery is synchronous; the signal is delivered inside this
+ *    function.  If a receiver was originally in another thread, the signal
+ *    is delivered in the thread where this function is called.  This means
+ *    that concurrency control (locking) is required if the application uses
+ *    events in multiple threads.
+ *
+ * EXAMPLE
+ *
+ *    silc_schedule_event_signal(schedule, "foo event", NULL, intarg, buffer);
+ *
+ ***/
+SilcBool silc_schedule_event_signal(SilcSchedule schedule, const char *event,
+				    SilcTask task, ...);
 
 #endif