*/
-/****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,
* 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 register
- * 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 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
* 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. Each scheduler in worker thread should be a child
- * scheduler created from the main thread's parent schedule.
+ * 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/SilcTaskEventCallback
+/****f* silcutil/SilcTaskEventCallback
*
* SYNOPSIS
*
SilcTask task, void *context,
va_list va);
-/****f* silcutil/SilcScheduleAPI/SilcTaskNotifyCb
+/****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/SilcScheduleAPI/SILC_TASK_EVENT_CALLBACK
+/****d* silcutil/SILC_TASK_EVENT_CALLBACK
*
* NAME
*
#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, 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_parent
+/****f* silcutil/silc_schedule_get_parent
*
* SYNOPSIS
*
***/
SilcSchedule silc_schedule_get_parent(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_get_context
+/****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_add_event
+/****f* silcutil/silc_schedule_task_add_event
*
* SYNOPSIS
*
*
* 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. This function returns the event task context or NULL on error.
+ * 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_BUFFER,
+ * SILC_PARAM_END);
*
* // Connect to 'connected' event
* silc_schedule_event_connect(schedule, "connected", NULL,
SilcTask silc_schedule_task_add_event(SilcSchedule schedule,
const char *event, ...);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
+/****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_task_del_event
+/****f* silcutil/silc_schedule_task_del_event
*
* SYNOPSIS
*
SilcBool silc_schedule_task_del_event(SilcSchedule schedule,
const char *event);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
+/****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/SilcScheduleAPI/silc_schedule_event_connect
+/****f* silcutil/silc_schedule_event_connect
*
* SYNOPSIS
*
SilcTaskEventCallback callback,
void *context);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_event_disconnect
+/****f* silcutil/silc_schedule_event_disconnect
*
* SYNOPSIS
*
SilcTaskEventCallback callback,
void *context);
-/****f* silcutil/SilcScheduleAPI/silc_schedule_event_signal
+/****f* silcutil/silc_schedule_event_signal
*
* SYNOPSIS
*
*
* 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 task to be signalled. It is marginally faster
- * to use the `task' pointer directly instead of `event' to send the signal.
+ * 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.
+ * 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
projects / runtime.git / blobdiff