Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1998 - 2007 Pekka Riikonen
+ Copyright (C) 1998 - 2008 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
*/
-/****h* silcutil/SILC Schedule Interface
+/****h* silcutil/Scheduler Interface
*
* DESCRIPTION
*
* 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 supports file descriptor based tasks, timeout tasks and
+ * asynchronous event tasks. File descriptor tasks are tasks that perform
+ * some operation over the specified file descriptor or socket. The timeout
+ * tasks are timeouts that are executed after the specified timeout has
+ * elapsed. Asynchronous event tasks are tasks that can be connected to
+ * and signalled to deliver messages and data to all connected entities.
*
* 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
+ * SILC Scheduler does support running the scheduler only one iteration, 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
+ * On Windows 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
* 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.
+ * On Symbian OS the SILC Scheduler can work in cooperation with the Active
+ * Scheduler. However, the Symbian OS Active Scheduler must be started
+ * before starting SILC Scheduler.
+ *
+ * The SILC Scheduler supports multi-threads. Each thread can have their
+ * own scheduler. Tasks registered to a scheduler are always executed in
+ * that same thread. However, tasks may be added to and removed from any
+ * scheduler from any thread. Each scheduler in worker thread should be
+ * a child scheduler created from the main thread's parent scheduler.
*
***/
#ifndef SILCSCHEDULE_H
#define SILCSCHEDULE_H
-/****s* silcutil/SilcScheduleAPI/SilcSchedule
+/****s* silcutil/SilcSchedule
*
* NAME
*
***/
typedef struct SilcScheduleStruct *SilcSchedule;
-/****s* silcutil/SilcScheduleAPI/SilcTask
+/****s* silcutil/SilcTask
*
* NAME
*
***/
typedef struct SilcTaskStruct *SilcTask;
-/****d* silcutil/SilcScheduleAPI/SilcTaskEvent
+/****d* silcutil/SilcTaskEvent
*
* NAME
*
} SilcTaskEvent;
/***/
-/****f* silcutil/SilcScheduleAPI/SilcTaskCallback
+/****f* silcutil/SilcTaskCallback
*
* SYNOPSIS
*
SilcTaskEvent type, SilcUInt32 fd,
void *context);
-/****f* silcutil/SilcScheduleAPI/SilcTaskNotifyCb
+/****f* silcutil/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/SilcTaskNotifyCb
*
* SYNOPSIS
*
/* Macros */
-/****d* silcutil/SilcScheduleAPI/SILC_ALL_TASKS
+/****d* silcutil/SILC_ALL_TASKS
*
* NAME
*
#define SILC_ALL_TASKS ((SilcTask)1)
/***/
-/****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
+/****d* silcutil/SILC_TASK_CALLBACK
*
* NAME
*
SilcUInt32 fd, void *context)
/***/
+/****d* silcutil/SILC_TASK_EVENT_CALLBACK
+ *
+ * NAME
+ *
+ * #define SILC_TASK_EVENT_CALLBACK ...
+ *
+ * DESCRIPTION
+ *
+ * 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_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
+/****f* silcutil/silc_schedule_init
*
* SYNOPSIS
*
* SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
- * SilcStack stack);
+ * 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 `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.
+ * 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
* 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
*
***/
SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
- SilcStack stack);
+ SilcStack stack, SilcSchedule parent);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
+/****f* silcutil/silc_schedule_uninit
*
* SYNOPSIS
*
***/
SilcBool silc_schedule_uninit(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_stop
+/****f* silcutil/silc_schedule_stop
*
* SYNOPSIS
*
***/
void silc_schedule_stop(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule
+/****f* silcutil/silc_schedule
*
* SYNOPSIS
*
***/
void silc_schedule(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_one
+/****f* silcutil/silc_schedule_one
*
* SYNOPSIS
*
***/
SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup
+/****f* silcutil/silc_schedule_wakeup
*
* SYNOPSIS
*
***/
void silc_schedule_wakeup(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_get_context
+/****f* silcutil/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/silc_schedule_get_context
*
* SYNOPSIS
*
***/
void *silc_schedule_get_context(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_get_stack
+/****f* silcutil/silc_schedule_get_stack
*
* SYNOPSIS
*
***/
SilcStack silc_schedule_get_stack(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_set_notify
+/****f* silcutil/silc_schedule_set_notify
*
* SYNOPSIS
*
void silc_schedule_set_notify(SilcSchedule schedule,
SilcTaskNotifyCb notify, void *context);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_set_global
+/****f* silcutil/silc_schedule_set_global
*
* SYNOPSIS
*
***/
void silc_schedule_set_global(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_get_global
+/****f* silcutil/silc_schedule_get_global
*
* SYNOPSIS
*
***/
SilcSchedule silc_schedule_get_global(void);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_fd
+/****f* silcutil/silc_schedule_task_add_fd
*
* SYNOPSIS
*
#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
+/****f* silcutil/silc_schedule_task_add_timeout
*
* SYNOPSIS
*
silc_schedule_task_add(schedule, 0, callback, context, s, u, \
SILC_TASK_TIMEOUT)
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_signal
+/****f* silcutil/silc_schedule_task_add_signal
*
* SYNOPSIS
*
silc_schedule_task_add(schedule, sig, callback, context, 0, 0, \
SILC_TASK_SIGNAL)
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
+/****f* silcutil/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. The list must be ended with SILC_PARAM_END. 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,
+ * SILC_PARAM_END);
+ *
+ * // 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/silc_schedule_task_del
*
* SYNOPSIS
*
***/
SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd
+/****f* silcutil/silc_schedule_task_del_by_fd
*
* SYNOPSIS
*
***/
SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
+/****f* silcutil/silc_schedule_task_del_by_callback
*
* SYNOPSIS
*
SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
SilcTaskCallback callback);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context
+/****f* silcutil/silc_schedule_task_del_by_context
*
* SYNOPSIS
*
SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
void *context);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_all
+/****f* silcutil/silc_schedule_task_del_by_all
*
* SYNOPSIS
*
SilcTaskCallback callback,
void *context);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
+/****f* silcutil/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/silc_schedule_set_listen_fd
*
* SYNOPSIS
*
SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
SilcTaskEvent mask, SilcBool send_events);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_get_fd_events
+/****f* silcutil/silc_schedule_get_fd_events
*
* SYNOPSIS
*
SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
SilcUInt32 fd);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
+/****f* silcutil/silc_schedule_unset_listen_fd
*
* SYNOPSIS
*
***/
void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
+/****f* silcutil/silc_schedule_event_connect
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_schedule_event_connect(SilcSchedule schedule,
+ * const char *event, SilcTask task,
+ * SilcTaskEventCallback callback,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * 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);
+ *
+ ***/
+SilcBool silc_schedule_event_connect(SilcSchedule schedule,
+ const char *event, SilcTask task,
+ SilcTaskEventCallback callback,
+ void *context);
+
+/****f* silcutil/silc_schedule_event_disconnect
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
+ * const char *event, SilcTask task,
+ * SilcTaskEventCallback callback,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * 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.
+ *
+ ***/
+SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
+ const char *event, SilcTask task,
+ SilcTaskEventCallback callback,
+ void *context);
+
+/****f* silcutil/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 event 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. The variable argument list
+ * must not be ended with SILC_PARAM_END even though it is ended with that
+ * in silc_schedule_task_add_event.
+ *
+ * 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);
+ *
+ ***/
+SilcBool silc_schedule_event_signal(SilcSchedule schedule, const char *event,
+ SilcTask task, ...);
+
#endif
projects / runtime.git / blobdiff