Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1998 - 2005 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
***/
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
* 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,
/* Prototypes */
+#include "silcschedule_i.h"
+
/****f* silcutil/SilcScheduleAPI/silc_schedule_init
*
* SYNOPSIS
* 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);
*
* SYNOPSIS
*
- * bool silc_schedule_uninit(SilcSchedule schedule);
+ * SilcBool silc_schedule_uninit(SilcSchedule schedule);
*
* DESCRIPTION
*
* is still valid and silc_schedule_stop has not been called.
*
***/
-bool silc_schedule_uninit(SilcSchedule schedule);
+SilcBool silc_schedule_uninit(SilcSchedule schedule);
/****f* silcutil/SilcScheduleAPI/silc_schedule_stop
*
*
* 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);
*
* 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);
*
* 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
*
* 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) \
*
* 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, bool send_events);
+ * SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule,
+ * SilcUInt32 fd,
+ * SilcTaskEvent mask,
+ * SilcBool send_events);
*
* DESCRIPTION
*
* 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, bool 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
projects / silc.git / blobdiff