X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcschedule.h;h=e92bb830e45e989ad4e234c7d63227ff2f79206a;hb=196824372226561334cd638d6471267cbffb354c;hp=dffa714290bdf31b4bdc39c5397f79ee79c00035;hpb=42c15f8f9a4d42f8d2cbc92cd1fe5184cea56b85;p=silc.git diff --git a/lib/silcutil/silcschedule.h b/lib/silcutil/silcschedule.h index dffa7142..e92bb830 100644 --- a/lib/silcutil/silcschedule.h +++ b/lib/silcutil/silcschedule.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 1998 - 2006 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 @@ -95,34 +95,6 @@ typedef struct SilcScheduleStruct *SilcSchedule; ***/ typedef struct SilcTaskStruct *SilcTask; -/****d* silcutil/SilcScheduleAPI/SilcTaskType - * - * NAME - * - * typedef enum { ... } SilcTaskType; - * - * DESCRIPTION - * - * SILC has two types of tasks, non-timeout tasks (tasks that perform - * over file descriptors), and timeout tasks. 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 = 0, - - /* 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, -} SilcTaskType; -/***/ - /****d* silcutil/SilcScheduleAPI/SilcTaskEvent * * NAME @@ -176,6 +148,11 @@ typedef enum { * 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, @@ -219,6 +196,8 @@ void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \ /* Prototypes */ +#include "silcschedule_i.h" + /****f* silcutil/SilcScheduleAPI/silc_schedule_init * * SYNOPSIS @@ -233,11 +212,11 @@ void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \ * to all task callbacks. The caller must free that context. The * 'app_context' can be for example the application itself. * - * The `max_tasks' is the maximum number of SILC_TASK_FD 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). + * 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). * ***/ SilcSchedule silc_schedule_init(int max_tasks, void *app_context); @@ -284,9 +263,18 @@ void silc_schedule_stop(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. + * 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); @@ -295,7 +283,7 @@ void silc_schedule(SilcSchedule schedule); * * SYNOPSIS * - * SilcBool silc_schedule_one(SilcSchedule schedule, int block); + * SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs); * * DESCRIPTION * @@ -306,6 +294,11 @@ 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. + * ***/ SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs); @@ -317,12 +310,11 @@ SilcBool 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); @@ -337,59 +329,12 @@ void silc_schedule_wakeup(SilcSchedule schedule); * * Returns the application specific context that was saved into the * scheduler in silc_schedule_init function. The context is also - * returned to application in task callback functions, but this function + * 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_task_add - * - * SYNOPSIS - * - * SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd, - * SilcTaskCallback callback, - * void *context, - * long seconds, long useconds, - * SilcTaskType type); - * - * 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 (fd) 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 - * same `fd' can be added only once. - * - * 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. - * - * 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); - /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_fd * * SYNOPSIS @@ -400,8 +345,16 @@ SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd, * * DESCRIPTION * - * A convenience function to add fd task. You may use this if you - * don't want to use the silc_schedule_task_add function to add fd task. + * 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. * ***/ #define silc_schedule_task_add_fd(schedule, fd, callback, context) \ @@ -418,118 +371,156 @@ SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd, * * DESCRIPTION * - * A convenience function to add timeout task. You may use this if - * you don't want to use the silc_schedule_task_add function to add - * timeout task. + * 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. The task added with zero (0) + * timeout will be executed immediately next time tasks are scheduled. * ***/ #define silc_schedule_task_add_timeout(schedule, callback, context, s, u) \ - silc_schedule_task_add(schedule, 0, callback, context, s, u, \ - SILC_TASK_TIMEOUT) + 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. + * + * 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_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. * ***/ -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. * ***/ -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. * ***/ -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, - * void *context); + * SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule, + * void *context); * * DESCRIPTION * - * Deletes a task from the scheduler by the specified `context'. + * 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. * ***/ -void silc_schedule_task_del_by_context(SilcSchedule schedule, void *context); +SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule, + void *context); /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_all * * SYNOPSIS * - * void silc_schedule_task_del_by_all(SilcSchedule schedule, int fd, - * SilcTaskCallback callback, - * void *context); + * 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'. + * 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. * ***/ -void silc_schedule_task_del_by_all(SilcSchedule schedule, int fd, - SilcTaskCallback callback, void *context); +SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd, + SilcTaskCallback callback, + void *context); /****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd * * SYNOPSIS * - * void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd, - * SilcTaskEvent mask, - * SilcBool send_events); + * SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, + * SilcUInt32 fd, + * SilcTaskEvent mask, + * SilcBool send_events); * * DESCRIPTION * @@ -547,114 +538,42 @@ void silc_schedule_task_del_by_all(SilcSchedule schedule, int fd, * after the event occurs in reality. In normal cases the `send_events' * is set to FALSE. * - ***/ -void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd, - SilcTaskEvent mask, SilcBool send_events); - -/****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. - * - ***/ -void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd); - -/****f* silcutil/SilcScheduleAPI/silc_schedule_signal_register - * - * SYNOPSIS - * - * void silc_schedule_signal_register(SilcSchedule schedule, - * SilcUInt32 signal, - * SilcTaskCallback 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. - * The `callback' with `context' will be called after the application - * has called silc_schedule_signal_call function in the real signal - * callback. Application is responsible of calling that, and the - * signal system will not work without calling silc_schedule_signal_call - * function. The specified `signal' value will be also delivered to - * the `callback' as the fd-argument. The event type in the callback - * will be SILC_TASK_INTERRUPT. It is safe to use any SILC routines - * in the `callback' since it is actually called after the signal really - * happened. - * - * On platform that does not support signals calling this function has - * no effect. - * - * EXAMPLE - * - * Typical signal usage case on Unix systems: - * - * struct sigaction sa; - * sa.sa_handler = signal_handler; - * sigaction(SIGHUP, &sa, NULL); - * sigaction(SIGINT, &sa, NULL); - * silc_schedule_signal_register(schedule, SIGHUP, hup_signal, context); - * silc_schedule_signal_register(schedule, SIGINT, int_signal, context); - * - * static void signal_handler(int sig) - * { - * silc_schedule_signal_call(schedule, sig); - * } - * - * The `signal_handler' can be used as generic signal callback in the - * application that merely calls silc_schedule_signal_call, which then - * eventually will deliver for example the `hup_signal' callback. The - * same `signal_handler' can be used with all signals. + * Returns FALSE if the operation could not performed and TRUE if it + * was a success. * ***/ -void silc_schedule_signal_register(SilcSchedule schedule, SilcUInt32 signal, - SilcTaskCallback callback, void *context); +SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd, + SilcTaskEvent mask, SilcBool send_events); -/****f* silcutil/SilcScheduleAPI/silc_schedule_signal_unregister +/****f* silcutil/SilcScheduleAPI/silc_schedule_get_fd_events * * SYNOPSIS * - * void silc_schedule_signal_unregister(SilcSchedule schedule, - * SilcUInt32 signal, - * SilcTaskCallback callback, - * void *context); + * SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule, + * SilcUInt32 fd); * * DESCRIPTION * - * Unregister a signal indicated by `signal' from the scheduler. On - * platform that does not support signals calling this function has no - * effect. + * Returns the file descriptor `fd' current requested events mask, + * or 0 on error. * ***/ -void silc_schedule_signal_unregister(SilcSchedule schedule, SilcUInt32 signal, - SilcTaskCallback callback, void *context); +SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule, + SilcUInt32 fd); -/****f* silcutil/SilcScheduleAPI/silc_schedule_signal_call +/****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd * * SYNOPSIS * - * void silc_schedule_signal_call(SilcSchedule schedule, - * SilcUInt32 signal); + * void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd); * * DESCRIPTION * - * Mark the `signal' to be called later. Every signal that has been - * registered by silc_schedule_signal_register is delivered by calling - * this function. When signal really occurs, the application is - * responsible of calling this function in the signal handler. After - * signal is over the scheduler will then safely deliver the callback - * that was given to silc_schedule_signal_register function. + * 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. * ***/ -void silc_schedule_signal_call(SilcSchedule schedule, SilcUInt32 signal); - -#include "silcschedule_i.h" +void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd); #endif