***/
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,
-
- /* Platform specific process signal task. On Unix systems this is one of
- the signals described in signal(7). On other platforms this may not
- be available at all. Only one callback per signal may be added. */
- SILC_TASK_SIGNAL
-} 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,
void *context);
+/****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
*
* 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
*/
/* Prototypes */
+#include "silcschedule_i.h"
+
/****f* silcutil/SilcScheduleAPI/silc_schedule_init
*
* SYNOPSIS
*
- * SilcSchedule silc_schedule_init(int max_tasks, void *app_context);
+ * SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
+ * SilcStack stack);
*
* DESCRIPTION
*
* 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).
+ *
+ * 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, void *app_context);
+SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
+ SilcStack stack);
/****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
*
* scheduler could not be uninitialized. This happens when the scheduler
* is still valid and silc_schedule_stop has not been called.
*
+ * 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.
+ *
***/
SilcBool silc_schedule_uninit(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 program, but will continue dispatching
- * window messages, and thus can be used as the main loop of the program.
+ * 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 return immediately. On Symbian calling
- * silc_schedule is same as calling silc_schedule_one.
+ * 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
*
- * SilcBool silc_schedule_one(SilcSchedule schedule, int block);
+ * SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
*
* DESCRIPTION
*
*
* 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.
+ * this case the `timeout_usecs' is usually 0 to make the function
+ * return immediately.
*
***/
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);
*
* 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_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
* 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)
* 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)
+ * 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, \
* 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
* 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(SilcSchedule schedule, SilcTask task);
* 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_fd(SilcSchedule schedule, SilcUInt32 fd);
* 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_callback(SilcSchedule schedule,
SilcTaskCallback callback);
* 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);
* 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_all(SilcSchedule schedule, int fd,
SilcTaskCallback callback,
* 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.
*
* 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.
+ *
***/
SilcTaskEvent silc_schedule_get_fd_events(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);
-#include "silcschedule_i.h"
-
#endif