X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcschedule.h;h=e92bb830e45e989ad4e234c7d63227ff2f79206a;hp=07549c477091459d939ca3aa9a7331699def6df3;hb=196824372226561334cd638d6471267cbffb354c;hpb=262aba230e36a455a53fbde13f901a44472eae15 diff --git a/lib/silcutil/silcschedule.h b/lib/silcutil/silcschedule.h index 07549c47..e92bb830 100644 --- a/lib/silcutil/silcschedule.h +++ b/lib/silcutil/silcschedule.h @@ -1,26 +1,65 @@ -/****h* silcutil/silcschedule.h - * - * NAME - * - * silcschedule.h - * - * COPYRIGHT - * - * Author: Pekka Riikonen - * - * Copyright (C) 1998 - 2001 Pekka Riikonen +/* + + silcschedule.h + + Author: 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; 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 * - * 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. + * DESCRIPTION * - * 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. + * The SILC Scheduler is the heart of any application. The scheduler provides + * the application's main loop that can handle incoming data, outgoing data, + * timeouts and dispatch different kind of tasks. + * + * The SILC Scheduler supports file descriptor based tasks and timeout tasks. + * File descriptor tasks are tasks that perform some operation over the + * specified file descriptor. These include network connections, for example. + * The timeout tasks are timeouts that are executed after the specified + * timeout has elapsed. + * + * The SILC Scheduler is designed to be the sole main loop of the application + * so that the application does not need any other main loop. However, + * SILC Scheduler does support running the scheduler only once, so that the + * scheduler does not block, and thus providing a possiblity that some + * external main loop is run over the SILC Scheduler. + * + * Typical application first initializes the scheduler and then registers + * the very first tasks to the scheduler and then run the scheduler. After + * the scheduler's run function returns the application is considered to be + * ended. + * + * On WIN32 systems the SILC Scheduler is too designed to work as the main + * loop of the GUI application. It can handle all Windows messages and + * it dispatches them from the scheduler, and thus makes it possible to + * create GUI applications. The scheduler can also handle all kinds of + * WIN32 handles, this includes sockets created by the SILC Net API routines, + * WSAEVENT handle objects created by Winsock2 routines and arbitrary + * WIN32 HANDLE objects. + * + * The SILC Scheduler supports multi-threads as well. The actual scheduler + * must be run in single-thread but other threads may register new tasks + * and unregister old tasks. However, it is enforced that the actual + * task is always run in the main thread. The scheduler is context based + * which makes it possible to allocate several schedulers for one application. + * Since the scheduler must be run in single-thread, a multi-threaded + * application could be created by allocating own scheduler for each of the + * worker threads. * - */ + ***/ #ifndef SILCSCHEDULE_H #define SILCSCHEDULE_H @@ -28,104 +67,193 @@ /****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. * ***/ typedef struct SilcScheduleStruct *SilcSchedule; -/* Prototypes */ - -/****f* silcutil/SilcScheduleAPI/silc_schedule_init +/****s* silcutil/SilcScheduleAPI/SilcTask * - * SYNOPSIS + * NAME * - * SilcSchedule silc_schedule_init(SilcTaskQueue *fd_queue, - * SilcTaskQueue *timeout_queue, - * SilcTaskQueue *generic_queue, - * int max_fd); + * typedef struct SilcTaskStruct *SilcTask; * * DESCRIPTION * - * Initializes the scheduler. Sets the non-timeout task queue hook and - * the timeout task queue hook. This must be called before the scheduler - * is able to work. This will allocate the queue pointers if they are - * not allocated. Returns the scheduler context that must be freed by - * the silc_schedule_uninit function. + * This object represents one task in the scheduler. It is allocated + * by the silc_schedule_task_add function and freed by one of the + * silc_schedule_task_del* functions. * ***/ -SilcSchedule silc_schedule_init(SilcTaskQueue *fd_queue, - SilcTaskQueue *timeout_queue, - SilcTaskQueue *generic_queue, - int max_fd); +typedef struct SilcTaskStruct *SilcTask; -/****f* silcutil/SilcScheduleAPI/silc_schedule_uninit +/****d* silcutil/SilcScheduleAPI/SilcTaskEvent + * + * NAME + * + * typedef enum { ... } SilcTaskEvent; + * + * DESCRIPTION + * + * SILC Task event types. The event type indicates the occurred + * event of the task. This type will be given as argument to the + * SilcTaskCallback function to indicate the event for the caller. + * The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller + * of the silc_schedule_set_listen_fd, if the caller needs to control + * the events for the task. The SILC_TASK_EXPIRE is set always only + * by the scheduler when timeout expires for timeout task. The + * SILC_TASK_INTERRUPT is set for signal callback. + * + * SOURCE + */ +typedef enum { + SILC_TASK_READ = 0x0001, /* Reading */ + SILC_TASK_WRITE = 0x0002, /* Writing */ + SILC_TASK_EXPIRE = 0x0004, /* Timeout */ + SILC_TASK_INTERRUPT = 0x0008, /* Signal */ +} SilcTaskEvent; +/***/ + +/****f* silcutil/SilcScheduleAPI/SilcTaskCallback * * SYNOPSIS * - * bool silc_schedule_uninit(SilcSchedule schedule); + * typedef void (*SilcTaskCallback)(SilcSchedule schedule, + * void *app_context, + * SilcTaskEvent type, SilcUInt32 fd, + * void *context); * * DESCRIPTION * - * Uninitializes the schedule. This is called when the program is ready - * to end. This removes all tasks and task queues. Returns FALSE if the - * scheduler could not be uninitialized. This happens when the scheduler - * is still valid and silc_schedule_stop has not been called. + * The task callback function. This function will be called by the + * scheduler when some event of the task is performed. For example, + * when data is available from the connection this will be called. + * + * The `schedule' is the scheduler context, the `type' is the indicated + * event, the `fd' is the file descriptor of the task and the `context' + * is a caller specified context. If multiple events occurred this + * callback is called separately for all events. The `app_context' + * is application specific context that was given as argument to the + * silc_schedule_init function. If the task is timeout task then `fd' + * is zero (0). + * + * To specify task callback function in the application using the + * SILC_TASK_CALLBACK macro is recommended. + * + * The callback should not perform lenghty or blocking operations as + * this would also block all other waiting tasks. The task callback + * should either handle the operation fast or issue an asynchronous + * call (like to register 0 timeout task) to handle it later. * ***/ -bool silc_schedule_uninit(SilcSchedule schedule); +typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context, + SilcTaskEvent type, SilcUInt32 fd, + void *context); -/****f* silcutil/SilcScheduleAPI/silc_schedule_stop +/* 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 + * silc_schedule_task_del function to delete all tasks at once. + * + * SOURCE + */ +#define SILC_ALL_TASKS ((SilcTask)1) +/***/ + +/****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. + * + * SOURCE + */ +#define SILC_TASK_CALLBACK(func) \ +void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \ + SilcUInt32 fd, void *context) +/***/ + +/* Prototypes */ + +#include "silcschedule_i.h" + +/****f* silcutil/SilcScheduleAPI/silc_schedule_init * * SYNOPSIS * - * void silc_schedule_stop(SilcSchedule schedule); + * SilcSchedule silc_schedule_init(int max_tasks, void *app_context); * * DESCRIPTION * - * Stops the scheduler even if it is not supposed to be stopped yet. - * After calling this, one must call silc_schedule_uninit (after the - * silc_schedule has returned). + * Initializes the scheduler. This returns the scheduler context that + * is given as argument usually to all silc_schedule_* functions. + * The `app_context' is application specific context that is delivered + * 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 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). * ***/ -void silc_schedule_stop(SilcSchedule schedule); +SilcSchedule silc_schedule_init(int max_tasks, void *app_context); -/****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd +/****f* silcutil/SilcScheduleAPI/silc_schedule_uninit * * SYNOPSIS * - * void silc_schedule_set_listen_fd(SilcSchedule schedule, - * int fd, uint32 iomask); + * SilcBool silc_schedule_uninit(SilcSchedule schedule); * * DESCRIPTION * - * Sets a file descriptor to be listened by the scheduler. One can - * call this directly if wanted. This can be called multiple times for - * one file descriptor to set different iomasks. + * Uninitializes the scheduler. This is called when the program is ready + * to end. This removes all tasks from the scheduler. Returns FALSE if the + * scheduler could not be uninitialized. This happens when the scheduler + * is still valid and silc_schedule_stop has not been called. * ***/ -void silc_schedule_set_listen_fd(SilcSchedule schedule, int fd, uint32 iomask); +SilcBool silc_schedule_uninit(SilcSchedule schedule); -/****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd +/****f* silcutil/SilcScheduleAPI/silc_schedule_stop * * SYNOPSIS * - * void silc_schedule_unset_listen_fd(SilcSchedule schedule, int fd); + * void silc_schedule_stop(SilcSchedule schedule); * * DESCRIPTION * - * Removes a file descriptor from listen list. The file descriptor - * is not listened by the scheduler after this function. + * Stops the scheduler even if it is not supposed to be stopped yet. + * After calling this, one must call silc_schedule_uninit (after the + * silc_schedule has returned). After this is called it is guaranteed + * that next time the scheduler enters the main loop it will be stopped. + * However, untill it enters the main loop it will not detect that + * it is stopped for example if this is called from another thread. * ***/ -void silc_schedule_unset_listen_fd(SilcSchedule schedule, int fd); +void silc_schedule_stop(SilcSchedule schedule); /****f* silcutil/SilcScheduleAPI/silc_schedule * @@ -135,30 +263,44 @@ void silc_schedule_unset_listen_fd(SilcSchedule schedule, int fd); * * 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); -/****f* silcutil/SilcScheduleAPI/silc_schedule +/****f* silcutil/SilcScheduleAPI/silc_schedule_one * * SYNOPSIS * - * bool silc_schedule_one(SilcSchedule schedule, int block); + * SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs); * * DESCRIPTION * * Same as the silc_schedule but runs the scheduler only one round * and then returns. This function is handy when the SILC scheduler * is used inside some other external scheduler, for example. If - * the `timeout_usecs' is positive a timeout will be added to the + * the `timeout_usecs' is non-negative a timeout will be added to the * scheduler. The function will not return in this timeout unless * some other event occurs. * + * Typically this would be called from a timeout or idle task + * periodically (typically from 5-50 ms) to schedule SILC tasks. In + * this case the `timeout_usecs' is usually 0 to make the function + * return immediately. + * ***/ -bool silc_schedule_one(SilcSchedule schedule, int timeout_usecs); +SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs); /****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup * @@ -168,14 +310,270 @@ 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 task queues. This is called to wake up the scheduler in the - * main thread so that it detects the changes in the task queues. + * 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_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_task_add_fd + * + * SYNOPSIS + * + * SilcTask + * silc_schedule_task_add_fd(SilcSchedule schedule, SilcUInt32 fd, + * SilcTaskCallback callback, void *context); + * + * DESCRIPTION + * + * Add file descriptor task to scheduler. The `fd' may be either real + * file descriptor, socket or on some platforms an opaque file descriptor + * handle. To receive events for the file descriptor set the correct + * request events with silc_schedule_set_listen_fd function. + * + * The task will be initially set for SILC_TASK_READ events. Setting that + * event immediately after this call returns is not necessary. + * + * This returns the new task or NULL on error. If a task with `fd' has + * already been added this will return the existing task pointer. + * + ***/ +#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. 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) + +/****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 + * + * SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task); + * + * DESCRIPTION + * + * Deletes the `task' from the scheduler indicated by the `schedule'. + * After deleting the task it is guaranteed that the task callback + * will not be called. If the `task' is SILC_ALL_TASKS then all + * tasks is removed from the scheduler. Returns always TRUE. + * + * It is safe to call this function in any place. Tasks may be removed + * in task callbacks (including in the task's own task callback) and + * in multi-threaded environment in other threads as well. + * + ***/ +SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd + * + * SYNOPSIS + * + * SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, + * SilcUInt32 fd); + * + * DESCRIPTION + * + * Deletes a task from the scheduler by the specified `fd'. Returns + * FALSE if such fd task does not exist. + * + * It is safe to call this function in any place. Tasks may be removed + * in task callbacks (including in the task's own task callback) and + * in multi-threaded environment in other threads as well. + * + ***/ +SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback + * + * SYNOPSIS + * + * SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule, + * SilcTaskCallback callback); + * + * DESCRIPTION + * + * Deletes a task from the scheduler by the specified `callback' task + * callback function. Returns FALSE if such task with such callback + * does not exist. + * + * It is safe to call this function in any place. Tasks may be removed + * in task callbacks (including in the task's own task callback) and + * in multi-threaded environment in other threads as well. + * + ***/ +SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule, + SilcTaskCallback callback); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context + * + * SYNOPSIS + * + * SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule, + * void *context); + * + * DESCRIPTION + * + * Deletes a task from the scheduler by the specified `context'. Returns + * FALSE if such task with such context does not exist. + * + * It is safe to call this function in any place. Tasks may be removed + * in task callbacks (including in the task's own task callback) and + * in multi-threaded environment in other threads as well. + * + ***/ +SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule, + void *context); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_all + * + * SYNOPSIS + * + * SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd, + * SilcTaskCallback callback, + * void *context); + * + * DESCRIPTION + * + * Deletes a task from the scheduler by the specified `fd', `callback' + * and `context'. Returns FALSE if such task does not exist. + * + * It is safe to call this function in any place. Tasks may be removed + * in task callbacks (including in the task's own task callback) and + * in multi-threaded environment in other threads as well. + * + ***/ +SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd, + SilcTaskCallback callback, + void *context); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd + * + * SYNOPSIS + * + * SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, + * SilcUInt32 fd, + * SilcTaskEvent mask, + * SilcBool send_events); + * + * DESCRIPTION + * + * Sets a file descriptor `fd' to be listened by the scheduler for + * `mask' events. To tell scheduler not to listen anymore for this + * file descriptor call the silc_schedule_unset_listen_fd function. + * When new task is created with silc_schedule_task_add the event + * for the task's fd is initially set to SILC_TASK_READ. If you need + * to control the task's fd's events you must call this function + * whenever you need to change the events. This can be called multiple + * times to change the events. + * + * If the `send_events' is TRUE then this function sends the events + * in `mask' to the application. If FALSE then they are sent only + * after the event occurs in reality. In normal cases the `send_events' + * is set to FALSE. + * + * 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. + * + ***/ +SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule, + SilcUInt32 fd); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd + * + * SYNOPSIS + * + * void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd); + * + * DESCRIPTION + * + * Tells the scheduler not to listen anymore for the specified + * file descriptor `fd'. No events will be detected for the `fd' + * after calling this function. + * + ***/ +void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd); + #endif