/*
-
+
silcschedule.h
-
- COPYRIGHT
-
+
Author: Pekka Riikonen <priikone@silcnet.org>
-
- Copyright (C) 1998 - 2001 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
GNU General Public License for more details.
*/
-
+
/****h* silcutil/SILC Schedule Interface
*
* DESCRIPTION
* 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, timeout tasks
- * and generic 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 generic tasks are tasks that
- * apply to all registered file descriptors thus providing one task that
- * applies to many independent connections.
+ * 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. However, these
- * applications are considered to be special cases.
+ * 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
+ * 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
* 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
+ * WSAEVENT handle objects created by Winsock2 routines and arbitrary
* WIN32 HANDLE objects.
*
* The SILC Scheduler supports multi-threads as well. The actual scheduler
/****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
+ * to all silc_schedule_* functions. It must be freed by the
* silc_schedule_uninit function.
*
***/
/****s* silcutil/SilcScheduleAPI/SilcTask
*
* NAME
- *
+ *
* typedef struct SilcTaskStruct *SilcTask;
*
* DESCRIPTION
***/
typedef struct SilcTaskStruct *SilcTask;
-/****d* silcutil/SilcScheduleAPI/SilcTaskType
- *
- * NAME
- *
- * typedef enum { ... } SilcTaskType;
- *
- * DESCRIPTION
- *
- * SILC has three types of tasks, non-timeout tasks (tasks that perform
- * over file descriptors), timeout tasks and generic tasks (tasks that
- * apply to every file descriptor). This type is sent as argument for the
- * task registering function, silc_schedule_task_add.
- *
- * SOURCE
- */
-typedef enum {
- /* File descriptor task that performs some event over file descriptors.
- These tasks are for example network connections. */
- SILC_TASK_FD,
-
- /* Timeout tasks are tasks that are executed after the specified
- time has elapsed. After the task is executed the task is removed
- automatically from the scheduler. It is safe to re-register the
- task in task callback. It is also safe to unregister a task in
- the task callback. */
- SILC_TASK_TIMEOUT,
-
- /* Generic tasks are non-timeout tasks and they apply to all file
- descriptors, except to those that have explicitly registered a
- non-timeout task. These tasks are there to make it simpler and faster
- to execute common code that applies to all connections. These are,
- for example, receiving packets from network and sending packets to
- network. It doesn't make much sense to register a task that receives
- a packet from network to every connection when you can have one task
- that applies to all connections. This is what generic tasks are for.
- Generic tasks are not bound to any specific file descriptor, however,
- the correct file descriptor must be passed as argument to task
- registering function. */
- SILC_TASK_GENERIC,
-} SilcTaskType;
-/***/
-
/****d* silcutil/SilcScheduleAPI/SilcTaskEvent
*
* NAME
- *
+ *
* typedef enum { ... } SilcTaskEvent;
*
* DESCRIPTION
* 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.
+ * 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_READ = 0x0001, /* Reading */
+ SILC_TASK_WRITE = 0x0002, /* Writing */
+ SILC_TASK_EXPIRE = 0x0004, /* Timeout */
+ SILC_TASK_INTERRUPT = 0x0008, /* Signal */
} SilcTaskEvent;
/***/
-/****d* silcutil/SilcScheduleAPI/SilcTaskPriority
- *
- * NAME
- *
- * typedef enum { ... } SilcTaskPriority;
- *
- * DESCRIPTION
- *
- * Task priorities. Tasks may be registered with different priorities.
- * This type defines the different task priorities. The priorities
- * behaves same for all type of tasks, fd tasks, timeout tasks and
- * generic tasks.
- *
- * SOURCE
- */
-typedef enum {
- /* Lowest priority. The task is scheduled to run after its timeout
- has expired only and only when every other task with higher priority
- has already been run. For non-timeout tasks this priority behaves
- same way. Life is not fair for tasks with this priority. */
- SILC_TASK_PRI_LOW,
-
- /* Normal priority that is used mostly in SILC. This is priority that
- should always be used unless you specificly need some other priority.
- The scheduler will run this task as soon as its timeout has expired.
- For non-timeout tasks this priority behaves same way. Tasks are run
- in FIFO (First-In-First-Out) order. */
- SILC_TASK_PRI_NORMAL,
-} SilcTaskPriority;
-/***/
-
/****f* silcutil/SilcScheduleAPI/SilcTaskCallback
*
* SYNOPSIS
*
- * typedef void (*SilcTaskCallback)(SilcSchedule schedule,
- * SilcTaskEvent type, SilcUInt32 fd,
+ * typedef void (*SilcTaskCallback)(SilcSchedule schedule,
+ * void *app_context,
+ * SilcTaskEvent type, SilcUInt32 fd,
* void *context);
*
* DESCRIPTION
* 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.
+ * 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 and SILC_TASK_CALLBACK_GLOBAL macros is
- * recommended.
+ * 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, SilcTaskEvent type,
- SilcUInt32 fd, void *context);
+typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context,
+ SilcTaskEvent type, SilcUInt32 fd,
+ void *context);
+
+/****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);
+
+/****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);
/* Macros */
/****d* silcutil/SilcScheduleAPI/SILC_ALL_TASKS
*
* NAME
- *
+ *
* #define SILC_ALL_TASKS ...
*
* DESCRIPTION
*
- * Marks for all tasks in the scheduler. This can be passed to
+ * Marks for all tasks in the scheduler. This can be passed to
* silc_schedule_task_del function to delete all tasks at once.
*
* SOURCE
/****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
*
* NAME
- *
+ *
* #define SILC_TASK_CALLBACK ...
*
* DESCRIPTION
*
- * Generic macro to define task callback functions. This defines a
- * static function with name `func' as a task callback function.
+ * 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) \
-static void func(SilcSchedule schedule, SilcTaskEvent type, \
- SilcUInt32 fd, void *context)
+#define SILC_TASK_CALLBACK(func) \
+void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \
+ SilcUInt32 fd, void *context)
/***/
-/****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK_GLOBAL
+/****d* silcutil/SilcScheduleAPI/SILC_TASK_EVENT_CALLBACK
*
* NAME
- *
- * #define SILC_TASK_CALLBACK_GLOBAL ...
+ *
+ * #define SILC_TASK_EVENT_CALLBACK ...
*
* DESCRIPTION
*
- * Generic macro to define task callback functions. This defines a
- * function with name `func' as a task callback function. This
- * differs from SILC_TASK_CALLBACK in that the defined function is
- * not static.
+ * 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_CALLBACK_GLOBAL(func) \
-void func(SilcSchedule schedule, SilcTaskEvent type, \
- SilcUInt32 fd, void *context)
+#define SILC_TASK_EVENT_CALLBACK(func) \
+SilcBool func(SilcSchedule schedule, void *app_context, \
+ SilcTask task, void *context, va_list va)
+
/***/
/* Prototypes */
+#include "silcschedule_i.h"
+
/****f* silcutil/SilcScheduleAPI/silc_schedule_init
*
* SYNOPSIS
*
- * SilcSchedule silc_schedule_init(int max_tasks);
+ * SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
+ * SilcStack stack, SilcSchedule parent);
*
* DESCRIPTION
*
- * Initializes the scheduler. This returns the scheduler context that
- * is given as argument usually to all silc_schedule_* functions.
- * The `max_tasks' indicates the number of maximum tasks that the
- * scheduler can handle.
+ * 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);
+SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
+ SilcStack stack, SilcSchedule parent);
/****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
*
* SYNOPSIS
*
- * bool silc_schedule_uninit(SilcSchedule schedule);
+ * SilcBool silc_schedule_uninit(SilcSchedule schedule);
*
* DESCRIPTION
*
* scheduler could not be uninitialized. This happens when the scheduler
* is still valid and silc_schedule_stop has not been called.
*
- ***/
-bool silc_schedule_uninit(SilcSchedule schedule);
-
-/****f* silcutil/SilcScheduleAPI/silc_schedule_reinit
- *
- * SYNOPSIS
- *
- * SilcSchedule silc_schedule_reinit(int max_tasks);
- *
- * DESCRIPTION
- *
- * This function can be called to enlarge the task handling capabilities
- * of the scheduler indicated by `schedule'. The `max_tasks' must be
- * larger than what was set in silc_schedule_init function. This function
- * returns FALSE if it cannot reinit the scheduler. This function does
- * not do anything else except ready the scheduler to handle `max_tasks'
- * number of tasks after this function returns. It is safe to call this
- * function at any time, and it is guaranteed that existing tasks remain
- * as they are in the scheduler.
+ * 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.
*
***/
-bool silc_schedule_reinit(SilcSchedule schedule, int max_tasks);
+SilcBool silc_schedule_uninit(SilcSchedule schedule);
/****f* silcutil/SilcScheduleAPI/silc_schedule_stop
*
*
* 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
+ * 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
*
* DESCRIPTION
*
- * The SILC scheduler. This is actually the main routine in SILC programs.
- * When this returns the program is to be ended. Before this function can
- * be called, one must call silc_schedule_init function.
+ * 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);
*
* SYNOPSIS
*
- * bool silc_schedule_one(SilcSchedule schedule, int block);
+ * SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
*
* DESCRIPTION
*
* 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.
+ *
***/
-bool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
+SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
/****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup
*
*
* DESCRIPTION
*
- * Wakes up the scheduler. This is used only in multi-threaded
+ * 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.
- * Implementation of this function may be platform specific.
*
***/
void silc_schedule_wakeup(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_add
+/****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);
+
+/****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);
+
+/****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);
+
+/****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);
+
+/****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(SilcSchedule schedule, SilcUInt32 fd,
- * SilcTaskCallback callback,
- * void *context,
- * long seconds, long useconds,
- * SilcTaskType type,
- * SilcTaskPriority priority);
- *
- * DESCRIPTION
- *
- * Registers a new task to the scheduler. This same function is used
- * to register all types of tasks. The `type' argument tells what type
- * of the task is. Note that when registering non-timeout tasks one
- * should also pass 0 as timeout, as the timeout will be ignored anyway.
- * Also, note, that one cannot register timeout task with 0 timeout.
- * There cannot be zero timeouts, passing zero means no timeout is used
- * for the task and SILC_TASK_FD is used as default task type in
- * this case.
- *
- * The `schedule' is the scheduler context. The `fd' is the file
- * descriptor of the task. On WIN32 systems the `fd' is not actual
- * file descriptor but some WIN32 event handle. On WIN32 system the `fd'
- * may be a socket created by the SILC Net API routines, WSAEVENT object
- * created by Winsock2 network routines or arbitrary WIN32 HANDLE object.
- * On Unix systems the `fd' is always the real file descriptor.
- *
- * The `callback' is the task callback that will be called when some
- * event occurs for this task. The `context' is sent as argument to
- * the task `callback' function. For timeout tasks the callback is
- * called after the specified timeout has elapsed.
- *
- * If the `type' is SILC_TASK_TIMEOUT then `seconds' and `useconds'
- * may be non-zero. Otherwise they should be zero. The `priority'
- * indicates the priority of the task.
- *
- * It is always safe to call this function in any place. New tasks
- * may be added also in task callbacks, and in multi-threaded environment
- * in other threads as well.
- *
- ***/
-SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
- SilcTaskCallback callback, void *context,
- long seconds, long useconds,
- SilcTaskType type,
- SilcTaskPriority priority);
+ * 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
*
- * void silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
+ * 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.
+ * 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.
+ *
***/
-void silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
+SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd
*
* SYNOPSIS
*
- * void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
+ * SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule,
+ * SilcUInt32 fd);
*
* DESCRIPTION
*
- * Deletes a task from the scheduler by the specified `fd'.
+ * 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.
*
- * Note that generic tasks cannot be deleted using this function
- * since generic tasks does not match any specific fd.
+ * If `schedule' is NULL this will call silc_schedule_get_global to try to
+ * get global scheduler.
*
***/
-void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
+SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
*
* SYNOPSIS
*
- * void silc_schedule_task_del_by_callback(SilcSchedule schedule,
- * SilcTaskCallback callback);
+ * 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.
+ * 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.
+ *
***/
-void silc_schedule_task_del_by_callback(SilcSchedule schedule,
- SilcTaskCallback callback);
+SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
+ SilcTaskCallback callback);
/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context
*
* SYNOPSIS
*
- * void silc_schedule_task_del_by_context(SilcSchedule schedule,
+ * 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 `context'.
+ * 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.
+ *
***/
-void silc_schedule_task_del_by_context(SilcSchedule schedule, void *context);
+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
*
- * void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
- * SilcTaskEvent mask);
+ * SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule,
+ * SilcUInt32 fd,
+ * SilcTaskEvent mask,
+ * SilcBool send_events);
*
* DESCRIPTION
*
* 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.
+ *
***/
-void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
- SilcTaskEvent mask);
+SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
+ SilcUInt32 fd);
/****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
*
* 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_signal_register
+/****f* silcutil/SilcScheduleAPI/silc_schedule_event_connect
*
* SYNOPSIS
*
- * void silc_schedule_signal_register(SilcSchedule schedule,
- * SilcUInt32 signal);
+ * SilcBool silc_schedule_event_connect(SilcSchedule schedule,
+ * const char *event, SilcTask task,
+ * SilcTaskEventCallback callback,
+ * void *context);
*
* DESCRIPTION
*
- * Register signal indicated by `signal' to the scheduler. Application
- * should register all signals it is going to use to the scheduler.
- * To unregister a signal call silc_schedule_signal_unregister. On
- * platform that does not support signals calling this function has not
- * effect.
+ * 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);
*
***/
-void silc_schedule_signal_register(SilcSchedule schedule, SilcUInt32 signal);
+SilcBool silc_schedule_event_connect(SilcSchedule schedule,
+ const char *event, SilcTask task,
+ SilcTaskEventCallback callback,
+ void *context);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_signal_unregister
+/****f* silcutil/SilcScheduleAPI/silc_schedule_event_disconnect
*
* SYNOPSIS
*
- * void silc_schedule_signal_unregister(SilcSchedule schedule,
- * SilcUInt32 signal);
+ * SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
+ * const char *event, SilcTask task,
+ * SilcTaskEventCallback callback,
+ * void *context);
*
* DESCRIPTION
*
- * Unregister a signal indicated by `signal' from the scheduler. On
- * platform that does not support signals calling this function has no
- * effect.
+ * 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);
*
***/
-void silc_schedule_signal_unregister(SilcSchedule schedule, SilcUInt32 signal);
+SilcBool silc_schedule_event_signal(SilcSchedule schedule, const char *event,
+ SilcTask task, ...);
#endif
projects / crypto.git / blobdiff