/* Routine to remove the task. Implemented in silctask.c. */
int silc_task_remove(SilcTaskQueue queue, SilcTask task);
+/* Routine to compare task timeouts. Implemented in silctask.c. */
+int silc_task_timeout_compare(struct timeval *smaller,
+ struct timeval *bigger);
+
/* System specific routines. Implemented under unix/ and win32/. */
/* System specific select(). */
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
+ # DESCRIPTION
+ *
+ * The SILC Scheduler is the heart of any application. The scheduler provides
+ * 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, timeout tasks
+ * and generic 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 generic tasks are tasks that
+ * apply to all registered file descriptors thus providing one task that
+ * applies to many independent connections.
+ *
+ * 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
+ * external main loop is run over the SILC Scheduler. However, these
+ * applications are considered to be special cases.
+ *
+ * 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.
+ *
+ * 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. However, in this case the schedulers must not share
+ * same task queues. Each of the schedulers must allocate their own
+ * task queues.
+ *
+ * See the SILC Task API for task management interface. It is used to
+ * register and unregister the actual tasks.
+ *
*/
#ifndef SILCSCHEDULE_H
*
* DESCRIPTION
*
- * Initializes the scheduler. Sets the non-timeout task queue hook and
- * the timeout task queue hook. This must be called before the scheduler
- * is able to work. This will allocate the queue pointers if they are
- * not allocated. Returns the scheduler context that must be freed by
- * the silc_schedule_uninit function.
+ * Initializes the scheduler. Sets the non-timeout task queue hook,
+ * the timeout task queue hook, and the generic task queue hook. This
+ * must be called before the scheduler is able to work. This will
+ * allocate the queue pointers if they are not allocated. Returns the
+ * scheduler context that must be freed by the silc_schedule_uninit
+ * function.
*
***/
SilcSchedule silc_schedule_init(SilcTaskQueue *fd_queue,
* Same as the silc_schedule but runs the scheduler only one round
* and then returns. This function is handy when the SILC scheduler
* is used inside some other external scheduler, for example. If
- * the `timeout_usecs' is positive a timeout will be added to the
+ * the `timeout_usecs' is non-negative a timeout will be added to the
* scheduler. The function will not return in this timeout unless
* some other event occurs.
*
#include "silcincludes.h"
+/* Routine to compare task timeouts. */
+int silc_task_timeout_compare(struct timeval *smaller,
+ struct timeval *bigger);
+
/* Allocates a new task queue into the Silc. If 'valid' is TRUE the
queue becomes valid task queue. If it is FALSE scheduler will skip
the queue. */
by silc_task_register function. Returns a pointer to the registered
task. */
-SilcTask silc_task_add(SilcTaskQueue queue, SilcTask new,
- SilcTaskPriority priority)
+static SilcTask silc_task_add(SilcTaskQueue queue, SilcTask new,
+ SilcTaskPriority priority)
{
SilcTask task, next, prev;
order. The priority matters if there are more than one task with
same timeout. */
-SilcTask silc_task_add_timeout(SilcTaskQueue queue, SilcTask new,
- SilcTaskPriority priority)
+static SilcTask silc_task_add_timeout(SilcTaskQueue queue, SilcTask new,
+ SilcTaskPriority priority)
{
SilcTask task, prev, next;
/* Macros */
-/* These can be used instead of calling directly the registering function.
- XXX: These are not used currently, maybe they should be :) */
-#define SILC_REGISTER_FD_TASK(queue, fd, cb, ctx, pri) \
- (silc_task_register((queue), (fd), (cb), (ctx), 0, 0, \
- SILC_TASK_FD, (pri)))
-#define SILC_REGISTER_TIMEOUT_TASK(queue, fd, cb, ctx, sec, usec, pri) \
- (silc_task_register((queue), (fd), (cb), (ctx), (sec), (usec), \
- SILC_TASK_TIMEOUT, (pri)))
-#define SILC_REGISTER_GENERIC_TASK(queue, fd, cb, ctx, pri) \
- (silc_task_register((queue), (fd), (cb), (ctx), 0, 0, \
- SILC_TASK_GENERIC, (pri)))
-
/* Generic macro to define task callback functions. This defines a function
with name 'func' as a task callback function. */
#define SILC_TASK_CALLBACK(func) \
bool valid);
void silc_task_queue_free(SilcTaskQueue queue);
void silc_task_queue_wakeup(SilcTaskQueue queue);
-SilcTask silc_task_add(SilcTaskQueue queue, SilcTask task,
- SilcTaskPriority priority);
-SilcTask silc_task_add_timeout(SilcTaskQueue queue, SilcTask task,
- SilcTaskPriority priority);
SilcTask silc_task_register(SilcTaskQueue queue, int fd,
SilcTaskCallback cb, void *context,
long seconds, long useconds,
void silc_task_unregister_by_context(SilcTaskQueue queue, void *context);
void silc_task_set_iotype(SilcTask task, int type);
void silc_task_reset_iotype(SilcTask task, int type);
-int silc_task_timeout_compare(struct timeval *smaller,
- struct timeval *bigger);
#endif
projects / silc.git / commitdiff