X-Git-Url: http://git.silcnet.org/gitweb/?p=crypto.git;a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcschedule.h;h=c37ecc6690dad71c522a4a29697ee2dbe5e8c7ae;hp=4b23067dd4cf566d7950448aafae8ddde8008304;hb=60180da59ffdbbd12058dded66e3c8a547cd0852;hpb=3391c18da03cb4f2ba77372702ec67e82e418cdc diff --git a/lib/silcutil/silcschedule.h b/lib/silcutil/silcschedule.h index 4b23067d..c37ecc66 100644 --- a/lib/silcutil/silcschedule.h +++ b/lib/silcutil/silcschedule.h @@ -1,25 +1,22 @@ /* - + silcschedule.h - - COPYRIGHT - + Author: Pekka Riikonen - - 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 @@ -28,24 +25,21 @@ * 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 @@ -53,7 +47,7 @@ * 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 @@ -73,14 +67,14 @@ /****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. * ***/ @@ -89,7 +83,7 @@ typedef struct SilcScheduleStruct *SilcSchedule; /****s* silcutil/SilcScheduleAPI/SilcTask * * NAME - * + * * typedef struct SilcTaskStruct *SilcTask; * * DESCRIPTION @@ -101,52 +95,10 @@ typedef struct SilcScheduleStruct *SilcSchedule; ***/ 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 @@ -157,54 +109,26 @@ typedef enum { * 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 @@ -216,27 +140,111 @@ typedef enum { * 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 @@ -247,64 +255,88 @@ typedef void (*SilcTaskCallback)(SilcSchedule schedule, SilcTaskEvent type, /****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 * @@ -313,28 +345,12 @@ SilcSchedule silc_schedule_init(int max_tasks); * 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 * @@ -344,8 +360,8 @@ bool silc_schedule_reinit(SilcSchedule schedule, int max_tasks); * * 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 @@ -362,9 +378,18 @@ void silc_schedule_stop(SilcSchedule schedule); * * 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); @@ -373,7 +398,7 @@ void silc_schedule(SilcSchedule schedule); * * SYNOPSIS * - * bool silc_schedule_one(SilcSchedule schedule, int block); + * SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs); * * DESCRIPTION * @@ -384,8 +409,13 @@ void silc_schedule(SilcSchedule schedule); * 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 * @@ -395,149 +425,410 @@ bool silc_schedule_one(SilcSchedule schedule, int timeout_usecs); * * 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 * @@ -550,9 +841,39 @@ void silc_schedule_task_del_by_context(SilcSchedule schedule, void *context); * 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 * @@ -566,41 +887,106 @@ void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 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