- * SilcTask silc_schedule_task_add(SilcSchedule schedule, uint32 fd,
- * SilcTaskCallback callback,
- * void *context,
- * long seconds, long useconds,
- * SilcTaskType type,
- * SilcTaskPriority priority);
- *
- * 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 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_TASK 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 `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. The `priority'
- * indicates the priority of the task.
- *
- * 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, uint32 fd,
- SilcTaskCallback callback, void *context,
- long seconds, long useconds,
- SilcTaskType type,
- SilcTaskPriority priority);
+ * 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_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
+ *
+ * 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.
+ *
+ * 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)
+
+/****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. 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, \
+ 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.
+ *
+ * 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
+ * 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_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. 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);
+ *
+ * // 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, ...);