7 Author: Pekka Riikonen <priikone@silcnet.org>
9 Copyright (C) 1998 - 2001 Pekka Riikonen
11 This program is free software; you can redistribute it and/or modify
12 it under the terms of the GNU General Public License as published by
13 the Free Software Foundation; either version 2 of the License, or
14 (at your option) any later version.
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
23 /****h* silcutil/SILC Schedule Interface
27 * The SILC Scheduler is the heart of any application. The scheduler provides
28 * the application's main loop that can handle incoming data, outgoing data,
29 * timeouts and dispatch different kind of tasks.
31 * The SILC Scheduler supports file descriptor based tasks, timeout tasks
32 * and generic tasks. File descriptor tasks are tasks that perform some
33 * operation over the specified file descriptor. These include network
34 * connections, for example. The timeout tasks are timeouts that are executed
35 * after the specified timeout has elapsed. The generic tasks are tasks that
36 * apply to all registered file descriptors thus providing one task that
37 * applies to many independent connections.
39 * The SILC Scheduler is designed to be the sole main loop of the application
40 * so that the application does not need any other main loop. However,
41 * SILC Scheduler does support running the scheduler only once, so that the
42 * scheduler does not block, and thus providing a possiblity that some
43 * external main loop is run over the SILC Scheduler. However, these
44 * applications are considered to be special cases.
46 * Typical application first initializes the scheduler and then registers
47 * the very first tasks to the scheduler and then run the scheduler. After
48 * the scheduler's run function returns the application is considered to be
51 * On WIN32 systems the SILC Scheduler is too designed to work as the main
52 * loop of the GUI application. It can handle all Windows messages and
53 * it dispatches them from the scheduler, and thus makes it possible to
54 * create GUI applications. The scheduler can also handle all kinds of
55 * WIN32 handles, this includes sockets created by the SILC Net API routines,
56 * WSAEVENT handle objects created by Winsock2 routines and arbitrary
57 * WIN32 HANDLE objects.
59 * The SILC Scheduler supports multi-threads as well. The actual scheduler
60 * must be run in single-thread but other threads may register new tasks
61 * and unregister old tasks. However, it is enforced that the actual
62 * task is always run in the main thread. The scheduler is context based
63 * which makes it possible to allocate several schedulers for one application.
64 * Since the scheduler must be run in single-thread, a multi-threaded
65 * application could be created by allocating own scheduler for each of the
70 #ifndef SILCSCHEDULE_H
71 #define SILCSCHEDULE_H
73 /****s* silcutil/SilcScheduleAPI/SilcSchedule
77 * typedef struct SilcScheduleStruct *SilcSchedule;
81 * This context is the actual Scheduler and is allocated by
82 * the silc_schedule_init funtion. The context is given as argument
83 * to all silc_schedule_* functions. It must be freed by the
84 * silc_schedule_uninit function.
87 typedef struct SilcScheduleStruct *SilcSchedule;
89 /****s* silcutil/SilcScheduleAPI/SilcTask
93 * typedef struct SilcTaskStruct *SilcTask;
97 * This object represents one task in the scheduler. It is allocated
98 * by the silc_schedule_task_add function and freed by one of the
99 * silc_schedule_task_del* functions.
102 typedef struct SilcTaskStruct *SilcTask;
104 /****d* silcutil/SilcScheduleAPI/SilcTaskType
108 * typedef enum { ... } SilcTaskType;
112 * SILC has three types of tasks, non-timeout tasks (tasks that perform
113 * over file descriptors), timeout tasks and generic tasks (tasks that
114 * apply to every file descriptor). This type is sent as argument for the
115 * task registering function, silc_schedule_task_add.
120 /* File descriptor task that performs some event over file descriptors.
121 These tasks are for example network connections. */
124 /* Timeout tasks are tasks that are executed after the specified
125 time has elapsed. After the task is executed the task is removed
126 automatically from the scheduler. It is safe to re-register the
127 task in task callback. It is also safe to unregister a task in
128 the task callback. */
131 /* Generic tasks are non-timeout tasks and they apply to all file
132 descriptors, except to those that have explicitly registered a
133 non-timeout task. These tasks are there to make it simpler and faster
134 to execute common code that applies to all connections. These are,
135 for example, receiving packets from network and sending packets to
136 network. It doesn't make much sense to register a task that receives
137 a packet from network to every connection when you can have one task
138 that applies to all connections. This is what generic tasks are for.
139 Generic tasks are not bound to any specific file descriptor, however,
140 the correct file descriptor must be passed as argument to task
141 registering function. */
146 /****d* silcutil/SilcScheduleAPI/SilcTaskEvent
150 * typedef enum { ... } SilcTaskEvent;
154 * SILC Task event types. The event type indicates the occurred
155 * event of the task. This type will be given as argument to the
156 * SilcTaskCallback function to indicate the event for the caller.
157 * The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller
158 * of the silc_schedule_set_listen_fd, if the caller needs to control
159 * the events for the task. The SILC_TASK_EXPIRE is set always only
160 * by the scheduler when timeout expires for timeout task. The
161 * SILC_TASK_INTERRUPT is set for signal callback.
166 SILC_TASK_READ = 0x0001, /* Reading */
167 SILC_TASK_WRITE = 0x0002, /* Writing */
168 SILC_TASK_EXPIRE = 0x0004, /* Timeout */
169 SILC_TASK_INTERRUPT = 0x0008, /* Signal */
173 /****d* silcutil/SilcScheduleAPI/SilcTaskPriority
177 * typedef enum { ... } SilcTaskPriority;
181 * Task priorities. Tasks may be registered with different priorities.
182 * This type defines the different task priorities. The priorities
183 * behaves same for all type of tasks, fd tasks, timeout tasks and
189 /* Lowest priority. The task is scheduled to run after its timeout
190 has expired only and only when every other task with higher priority
191 has already been run. For non-timeout tasks this priority behaves
192 same way. Life is not fair for tasks with this priority. */
193 SILC_TASK_PRI_LOW = 0,
195 /* Normal priority that is used mostly in SILC. This is priority that
196 should always be used unless you specificly need some other priority.
197 The scheduler will run this task as soon as its timeout has expired.
198 For non-timeout tasks this priority behaves same way. Tasks are run
199 in FIFO (First-In-First-Out) order. */
200 SILC_TASK_PRI_NORMAL,
204 /****f* silcutil/SilcScheduleAPI/SilcTaskCallback
208 * typedef void (*SilcTaskCallback)(SilcSchedule schedule,
210 * SilcTaskEvent type, SilcUInt32 fd,
215 * The task callback function. This function will be called by the
216 * scheduler when some event of the task is performed. For example,
217 * when data is available from the connection this will be called.
219 * The `schedule' is the scheduler context, the `type' is the indicated
220 * event, the `fd' is the file descriptor of the task and the `context'
221 * is a caller specified context. If multiple events occurred this
222 * callback is called separately for all events. The `app_context'
223 * is application specific context that was given as argument to the
224 * silc_schedule_init function.
226 * To specify task callback function in the application using the
227 * SILC_TASK_CALLBACK and SILC_TASK_CALLBACK_GLOBAL macros is
231 typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context,
232 SilcTaskEvent type, SilcUInt32 fd,
237 /****d* silcutil/SilcScheduleAPI/SILC_ALL_TASKS
241 * #define SILC_ALL_TASKS ...
245 * Marks for all tasks in the scheduler. This can be passed to
246 * silc_schedule_task_del function to delete all tasks at once.
250 #define SILC_ALL_TASKS ((SilcTask)1)
253 /****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
257 * #define SILC_TASK_CALLBACK ...
261 * Generic macro to define task callback functions. This defines a
262 * static function with name `func' as a task callback function.
266 #define SILC_TASK_CALLBACK(func) \
267 static void func(SilcSchedule schedule, void *app_context, \
268 SilcTaskEvent type, \
269 SilcUInt32 fd, void *context)
272 /****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK_GLOBAL
276 * #define SILC_TASK_CALLBACK_GLOBAL ...
280 * Generic macro to define task callback functions. This defines a
281 * function with name `func' as a task callback function. This
282 * differs from SILC_TASK_CALLBACK in that the defined function is
287 #define SILC_TASK_CALLBACK_GLOBAL(func) \
288 void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \
289 SilcUInt32 fd, void *context)
294 /****f* silcutil/SilcScheduleAPI/silc_schedule_init
298 * SilcSchedule silc_schedule_init(int max_tasks, void *app_context);
302 * Initializes the scheduler. This returns the scheduler context that
303 * is given as argument usually to all silc_schedule_* functions.
304 * The `max_tasks' indicates the number of maximum tasks that the
305 * scheduler can handle. The `app_context' is application specific
306 * context that is delivered to all task callbacks. The caller must
307 * free that context. The 'app_context' can be for example the
308 * application itself.
311 SilcSchedule silc_schedule_init(int max_tasks, void *app_context);
313 /****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
317 * bool silc_schedule_uninit(SilcSchedule schedule);
321 * Uninitializes the scheduler. This is called when the program is ready
322 * to end. This removes all tasks from the scheduler. Returns FALSE if the
323 * scheduler could not be uninitialized. This happens when the scheduler
324 * is still valid and silc_schedule_stop has not been called.
327 bool silc_schedule_uninit(SilcSchedule schedule);
329 /****f* silcutil/SilcScheduleAPI/silc_schedule_reinit
333 * SilcSchedule silc_schedule_reinit(int max_tasks);
337 * This function can be called to enlarge the task handling capabilities
338 * of the scheduler indicated by `schedule'. The `max_tasks' must be
339 * larger than what was set in silc_schedule_init function. This function
340 * returns FALSE if it cannot reinit the scheduler. This function does
341 * not do anything else except ready the scheduler to handle `max_tasks'
342 * number of tasks after this function returns. It is safe to call this
343 * function at any time, and it is guaranteed that existing tasks remain
344 * as they are in the scheduler.
347 bool silc_schedule_reinit(SilcSchedule schedule, int max_tasks);
349 /****f* silcutil/SilcScheduleAPI/silc_schedule_stop
353 * void silc_schedule_stop(SilcSchedule schedule);
357 * Stops the scheduler even if it is not supposed to be stopped yet.
358 * After calling this, one must call silc_schedule_uninit (after the
359 * silc_schedule has returned). After this is called it is guaranteed
360 * that next time the scheduler enters the main loop it will be stopped.
361 * However, untill it enters the main loop it will not detect that
362 * it is stopped for example if this is called from another thread.
365 void silc_schedule_stop(SilcSchedule schedule);
367 /****f* silcutil/SilcScheduleAPI/silc_schedule
371 * void silc_schedule(SilcSchedule schedule);
375 * The SILC scheduler. This is actually the main routine in SILC programs.
376 * When this returns the program is to be ended. Before this function can
377 * be called, one must call silc_schedule_init function.
380 void silc_schedule(SilcSchedule schedule);
382 /****f* silcutil/SilcScheduleAPI/silc_schedule_one
386 * bool silc_schedule_one(SilcSchedule schedule, int block);
390 * Same as the silc_schedule but runs the scheduler only one round
391 * and then returns. This function is handy when the SILC scheduler
392 * is used inside some other external scheduler, for example. If
393 * the `timeout_usecs' is non-negative a timeout will be added to the
394 * scheduler. The function will not return in this timeout unless
395 * some other event occurs.
398 bool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
400 /****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup
404 * void silc_schedule_wakeup(SilcSchedule schedule);
408 * Wakes up the scheduler. This is used only in multi-threaded
409 * environments where threads may add new tasks or remove old tasks
410 * from the scheduler. This is called to wake up the scheduler in the
411 * main thread so that it detects the changes in the scheduler.
412 * If threads support is not compiled in this function has no effect.
413 * Implementation of this function may be platform specific.
416 void silc_schedule_wakeup(SilcSchedule schedule);
418 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_context
422 * void *silc_schedule_get_context(SilcSchedule schedule);
426 * Returns the application specific context that was saved into the
427 * scheduler in silc_schedule_init function. The context is also
428 * returned to application in task callback functions, but this function
429 * may be used to get it as well if needed.
432 void *silc_schedule_get_context(SilcSchedule schedule);
434 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add
438 * SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
439 * SilcTaskCallback callback,
441 * long seconds, long useconds,
443 * SilcTaskPriority priority);
447 * Registers a new task to the scheduler. This same function is used
448 * to register all types of tasks. The `type' argument tells what type
449 * of the task is. Note that when registering non-timeout tasks one
450 * should also pass 0 as timeout, as the timeout will be ignored anyway.
451 * Also, note, that one cannot register timeout task with 0 timeout.
452 * There cannot be zero timeouts, passing zero means no timeout is used
453 * for the task and SILC_TASK_FD is used as default task type in
456 * The `schedule' is the scheduler context. The `fd' is the file
457 * descriptor of the task. On WIN32 systems the `fd' is not actual
458 * file descriptor but some WIN32 event handle. On WIN32 system the `fd'
459 * may be a socket created by the SILC Net API routines, WSAEVENT object
460 * created by Winsock2 network routines or arbitrary WIN32 HANDLE object.
461 * On Unix systems the `fd' is always the real file descriptor.
463 * The `callback' is the task callback that will be called when some
464 * event occurs for this task. The `context' is sent as argument to
465 * the task `callback' function. For timeout tasks the callback is
466 * called after the specified timeout has elapsed.
468 * If the `type' is SILC_TASK_TIMEOUT then `seconds' and `useconds'
469 * may be non-zero. Otherwise they should be zero. The `priority'
470 * indicates the priority of the task.
472 * It is always safe to call this function in any place. New tasks
473 * may be added also in task callbacks, and in multi-threaded environment
474 * in other threads as well.
477 SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
478 SilcTaskCallback callback, void *context,
479 long seconds, long useconds,
481 SilcTaskPriority priority);
483 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
487 * void silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
491 * Deletes the `task' from the scheduler indicated by the `schedule'.
492 * After deleting the task it is guaranteed that the task callback
493 * will not be called. If the `task' is SILC_ALL_TASKS then all
494 * tasks is removed from the scheduler.
496 * It is safe to call this function in any place. Tasks may be removed
497 * in task callbacks (including in the task's own task callback) and
498 * in multi-threaded environment in other threads as well.
501 void silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
503 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd
507 * void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
511 * Deletes a task from the scheduler by the specified `fd'.
513 * It is safe to call this function in any place. Tasks may be removed
514 * in task callbacks (including in the task's own task callback) and
515 * in multi-threaded environment in other threads as well.
517 * Note that generic tasks cannot be deleted using this function
518 * since generic tasks does not match any specific fd.
521 void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
523 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
527 * void silc_schedule_task_del_by_callback(SilcSchedule schedule,
528 * SilcTaskCallback callback);
532 * Deletes a task from the scheduler by the specified `callback' task
535 * It is safe to call this function in any place. Tasks may be removed
536 * in task callbacks (including in the task's own task callback) and
537 * in multi-threaded environment in other threads as well.
540 void silc_schedule_task_del_by_callback(SilcSchedule schedule,
541 SilcTaskCallback callback);
543 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context
547 * void silc_schedule_task_del_by_context(SilcSchedule schedule,
552 * Deletes a task from the scheduler by the specified `context'.
554 * It is safe to call this function in any place. Tasks may be removed
555 * in task callbacks (including in the task's own task callback) and
556 * in multi-threaded environment in other threads as well.
559 void silc_schedule_task_del_by_context(SilcSchedule schedule, void *context);
561 /****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
565 * void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
566 * SilcTaskEvent mask, bool send_events);
570 * Sets a file descriptor `fd' to be listened by the scheduler for
571 * `mask' events. To tell scheduler not to listen anymore for this
572 * file descriptor call the silc_schedule_unset_listen_fd function.
573 * When new task is created with silc_schedule_task_add the event
574 * for the task's fd is initially set to SILC_TASK_READ. If you need
575 * to control the task's fd's events you must call this function
576 * whenever you need to change the events. This can be called multiple
577 * times to change the events.
579 * If the `send_events' is TRUE then this function sends the events
580 * in `mask' to the application. If FALSE then they are sent only
581 * after the event occurs in reality. In normal cases the `send_events'
585 void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
586 SilcTaskEvent mask, bool send_events);
588 /****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
592 * void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
596 * Tells the scheduler not to listen anymore for the specified
597 * file descriptor `fd'. No events will be detected for the `fd'
598 * after calling this function.
601 void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
603 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_register
607 * void silc_schedule_signal_register(SilcSchedule schedule,
609 * SilcTaskCallback callback,
614 * Register signal indicated by `signal' to the scheduler. Application
615 * should register all signals it is going to use to the scheduler.
616 * The `callback' with `context' will be called after the application
617 * has called silc_schedule_signal_call function in the real signal
618 * callback. Application is responsible of calling that, and the
619 * signal system will not work without calling silc_schedule_signal_call
620 * function. The specified `signal' value will be also delivered to
621 * the `callback' as the fd-argument. The event type in the callback
622 * will be SILC_TASK_INTERRUPT. It is safe to use any SILC routines
623 * in the `callback' since it is actually called after the signal really
626 * On platform that does not support signals calling this function has
631 * Typical signal usage case on Unix systems:
633 * struct sigaction sa;
634 * sa.sa_handler = signal_handler;
635 * sigaction(SIGHUP, &sa, NULL);
636 * sigaction(SIGINT, &sa, NULL);
637 * silc_schedule_signal_register(schedule, SIGHUP, hup_signal, context);
638 * silc_schedule_signal_register(schedule, SIGINT, int_signal, context);
640 * static void signal_handler(int sig)
642 * silc_schedule_signal_call(schedule, sig);
645 * The `signal_handler' can be used as generic signal callback in the
646 * application that merely calls silc_schedule_signal_call, which then
647 * eventually will deliver for example the `hup_signal' callback. The
648 * same `signal_handler' can be used with all signals.
651 void silc_schedule_signal_register(SilcSchedule schedule, SilcUInt32 signal,
652 SilcTaskCallback callback, void *context);
654 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_unregister
658 * void silc_schedule_signal_unregister(SilcSchedule schedule,
660 * SilcTaskCallback callback,
665 * Unregister a signal indicated by `signal' from the scheduler. On
666 * platform that does not support signals calling this function has no
670 void silc_schedule_signal_unregister(SilcSchedule schedule, SilcUInt32 signal,
671 SilcTaskCallback callback, void *context);
673 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_call
677 * void silc_schedule_signal_call(SilcSchedule schedule,
678 * SilcUInt32 signal);
682 * Mark the `signal' to be called later. Every signal that has been
683 * registered by silc_schedule_signal_register is delivered by calling
684 * this function. When signal really occurs, the application is
685 * responsible of calling this function in the signal handler. After
686 * signal is over the scheduler will then safely deliver the callback
687 * that was given to silc_schedule_signal_register function.
690 void silc_schedule_signal_call(SilcSchedule schedule, SilcUInt32 signal);