5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1998 - 2005 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/SILC Schedule Interface
24 * The SILC Scheduler is the heart of any application. The scheduler provides
25 * the application's main loop that can handle incoming data, outgoing data,
26 * timeouts and dispatch different kind of tasks.
28 * The SILC Scheduler supports file descriptor based tasks and timeout tasks.
29 * File descriptor tasks are tasks that perform some operation over the
30 * specified file descriptor. These include network connections, for example.
31 * The timeout tasks are timeouts that are executed after the specified
32 * timeout has elapsed.
34 * The SILC Scheduler is designed to be the sole main loop of the application
35 * so that the application does not need any other main loop. However,
36 * SILC Scheduler does support running the scheduler only once, so that the
37 * scheduler does not block, and thus providing a possiblity that some
38 * external main loop is run over the SILC Scheduler.
40 * Typical application first initializes the scheduler and then registers
41 * the very first tasks to the scheduler and then run the scheduler. After
42 * the scheduler's run function returns the application is considered to be
45 * On WIN32 systems the SILC Scheduler is too designed to work as the main
46 * loop of the GUI application. It can handle all Windows messages and
47 * it dispatches them from the scheduler, and thus makes it possible to
48 * create GUI applications. The scheduler can also handle all kinds of
49 * WIN32 handles, this includes sockets created by the SILC Net API routines,
50 * WSAEVENT handle objects created by Winsock2 routines and arbitrary
51 * WIN32 HANDLE objects.
53 * The SILC Scheduler supports multi-threads as well. The actual scheduler
54 * must be run in single-thread but other threads may register new tasks
55 * and unregister old tasks. However, it is enforced that the actual
56 * task is always run in the main thread. The scheduler is context based
57 * which makes it possible to allocate several schedulers for one application.
58 * Since the scheduler must be run in single-thread, a multi-threaded
59 * application could be created by allocating own scheduler for each of the
64 #ifndef SILCSCHEDULE_H
65 #define SILCSCHEDULE_H
67 /****s* silcutil/SilcScheduleAPI/SilcSchedule
71 * typedef struct SilcScheduleStruct *SilcSchedule;
75 * This context is the actual Scheduler and is allocated by
76 * the silc_schedule_init funtion. The context is given as argument
77 * to all silc_schedule_* functions. It must be freed by the
78 * silc_schedule_uninit function.
81 typedef struct SilcScheduleStruct *SilcSchedule;
83 /****s* silcutil/SilcScheduleAPI/SilcTask
87 * typedef struct SilcTaskStruct *SilcTask;
91 * This object represents one task in the scheduler. It is allocated
92 * by the silc_schedule_task_add function and freed by one of the
93 * silc_schedule_task_del* functions.
96 typedef struct SilcTaskStruct *SilcTask;
98 /****d* silcutil/SilcScheduleAPI/SilcTaskType
102 * typedef enum { ... } SilcTaskType;
106 * SILC has two types of tasks, non-timeout tasks (tasks that perform
107 * over file descriptors), and timeout tasks. This type is sent as
108 * argument for the task registering function, silc_schedule_task_add.
113 /* File descriptor task that performs some event over file descriptors.
114 These tasks are for example network connections. */
117 /* Timeout tasks are tasks that are executed after the specified
118 time has elapsed. After the task is executed the task is removed
119 automatically from the scheduler. It is safe to re-register the
120 task in task callback. It is also safe to unregister a task in
121 the task callback. */
126 /****d* silcutil/SilcScheduleAPI/SilcTaskEvent
130 * typedef enum { ... } SilcTaskEvent;
134 * SILC Task event types. The event type indicates the occurred
135 * event of the task. This type will be given as argument to the
136 * SilcTaskCallback function to indicate the event for the caller.
137 * The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller
138 * of the silc_schedule_set_listen_fd, if the caller needs to control
139 * the events for the task. The SILC_TASK_EXPIRE is set always only
140 * by the scheduler when timeout expires for timeout task. The
141 * SILC_TASK_INTERRUPT is set for signal callback.
146 SILC_TASK_READ = 0x0001, /* Reading */
147 SILC_TASK_WRITE = 0x0002, /* Writing */
148 SILC_TASK_EXPIRE = 0x0004, /* Timeout */
149 SILC_TASK_INTERRUPT = 0x0008, /* Signal */
153 /****f* silcutil/SilcScheduleAPI/SilcTaskCallback
157 * typedef void (*SilcTaskCallback)(SilcSchedule schedule,
159 * SilcTaskEvent type, SilcUInt32 fd,
164 * The task callback function. This function will be called by the
165 * scheduler when some event of the task is performed. For example,
166 * when data is available from the connection this will be called.
168 * The `schedule' is the scheduler context, the `type' is the indicated
169 * event, the `fd' is the file descriptor of the task and the `context'
170 * is a caller specified context. If multiple events occurred this
171 * callback is called separately for all events. The `app_context'
172 * is application specific context that was given as argument to the
173 * silc_schedule_init function. If the task is timeout task then `fd'
176 * To specify task callback function in the application using the
177 * SILC_TASK_CALLBACK macro is recommended.
180 typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context,
181 SilcTaskEvent type, SilcUInt32 fd,
186 /****d* silcutil/SilcScheduleAPI/SILC_ALL_TASKS
190 * #define SILC_ALL_TASKS ...
194 * Marks for all tasks in the scheduler. This can be passed to
195 * silc_schedule_task_del function to delete all tasks at once.
199 #define SILC_ALL_TASKS ((SilcTask)1)
202 /****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
206 * #define SILC_TASK_CALLBACK ...
210 * Generic macro to define task callback functions. This defines a
211 * static function with name `func' as a task callback function.
215 #define SILC_TASK_CALLBACK(func) \
216 void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \
217 SilcUInt32 fd, void *context)
222 /****f* silcutil/SilcScheduleAPI/silc_schedule_init
226 * SilcSchedule silc_schedule_init(int max_tasks, void *app_context);
230 * Initializes the scheduler. This returns the scheduler context that
231 * is given as argument usually to all silc_schedule_* functions.
232 * The `app_context' is application specific context that is delivered
233 * to all task callbacks. The caller must free that context. The
234 * 'app_context' can be for example the application itself.
236 * The `max_tasks' is the maximum number of SILC_TASK_FD tasks in the
237 * scheduler. Set value to 0 to use default. Operating system will
238 * enforce the final limit. On some operating systems the limit can
239 * be significantly increased when this function is called in priviliged
240 * mode (as super user).
243 SilcSchedule silc_schedule_init(int max_tasks, void *app_context);
245 /****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
249 * bool silc_schedule_uninit(SilcSchedule schedule);
253 * Uninitializes the scheduler. This is called when the program is ready
254 * to end. This removes all tasks from the scheduler. Returns FALSE if the
255 * scheduler could not be uninitialized. This happens when the scheduler
256 * is still valid and silc_schedule_stop has not been called.
259 bool silc_schedule_uninit(SilcSchedule schedule);
261 /****f* silcutil/SilcScheduleAPI/silc_schedule_stop
265 * void silc_schedule_stop(SilcSchedule schedule);
269 * Stops the scheduler even if it is not supposed to be stopped yet.
270 * After calling this, one must call silc_schedule_uninit (after the
271 * silc_schedule has returned). After this is called it is guaranteed
272 * that next time the scheduler enters the main loop it will be stopped.
273 * However, untill it enters the main loop it will not detect that
274 * it is stopped for example if this is called from another thread.
277 void silc_schedule_stop(SilcSchedule schedule);
279 /****f* silcutil/SilcScheduleAPI/silc_schedule
283 * void silc_schedule(SilcSchedule schedule);
287 * The SILC scheduler. The program will run inside this function.
288 * When this returns the program is to be ended. Before this function can
289 * be called, one must call silc_schedule_init function.
292 void silc_schedule(SilcSchedule schedule);
294 /****f* silcutil/SilcScheduleAPI/silc_schedule_one
298 * bool silc_schedule_one(SilcSchedule schedule, int block);
302 * Same as the silc_schedule but runs the scheduler only one round
303 * and then returns. This function is handy when the SILC scheduler
304 * is used inside some other external scheduler, for example. If
305 * the `timeout_usecs' is non-negative a timeout will be added to the
306 * scheduler. The function will not return in this timeout unless
307 * some other event occurs.
310 bool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
312 /****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup
316 * void silc_schedule_wakeup(SilcSchedule schedule);
320 * Wakes up the scheduler. This is used only in multi-threaded
321 * environments where threads may add new tasks or remove old tasks
322 * from the scheduler. This is called to wake up the scheduler in the
323 * main thread so that it detects the changes in the scheduler.
324 * If threads support is not compiled in this function has no effect.
325 * Implementation of this function may be platform specific.
328 void silc_schedule_wakeup(SilcSchedule schedule);
330 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_context
334 * void *silc_schedule_get_context(SilcSchedule schedule);
338 * Returns the application specific context that was saved into the
339 * scheduler in silc_schedule_init function. The context is also
340 * returned to application in task callback functions, but this function
341 * may be used to get it as well if needed.
344 void *silc_schedule_get_context(SilcSchedule schedule);
346 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add
350 * SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
351 * SilcTaskCallback callback,
353 * long seconds, long useconds,
354 * SilcTaskType type);
358 * Registers a new task to the scheduler. This same function is used
359 * to register all types of tasks. The `type' argument tells what type
360 * of the task is. Note that when registering non-timeout (fd) tasks one
361 * should also pass 0 as timeout, as the timeout will be ignored anyway.
362 * Also, note, that one cannot register timeout task with 0 timeout.
363 * There cannot be zero timeouts, passing zero means no timeout is used
364 * for the task and SILC_TASK_FD is used as default task type in
367 * The `schedule' is the scheduler context. The `fd' is the file
368 * descriptor of the task. On WIN32 systems the `fd' is not actual
369 * file descriptor but some WIN32 event handle. On WIN32 system the `fd'
370 * may be a socket created by the SILC Net API routines, WSAEVENT object
371 * created by Winsock2 network routines or arbitrary WIN32 HANDLE object.
372 * On Unix systems the `fd' is always the real file descriptor. The
373 * same `fd' can be added only once.
375 * The `callback' is the task callback that will be called when some
376 * event occurs for this task. The `context' is sent as argument to
377 * the task `callback' function. For timeout tasks the callback is
378 * called after the specified timeout has elapsed.
380 * If the `type' is SILC_TASK_TIMEOUT then `seconds' and `useconds'
381 * may be non-zero. Otherwise they should be zero.
383 * It is always safe to call this function in any place. New tasks
384 * may be added also in task callbacks, and in multi-threaded environment
385 * in other threads as well.
388 SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
389 SilcTaskCallback callback, void *context,
390 long seconds, long useconds,
393 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_fd
398 * silc_schedule_task_add_fd(SilcSchedule schedule, SilcUInt32 fd,
399 * SilcTaskCallback callback, void *context);
403 * A convenience function to add fd task. You may use this if you
404 * don't want to use the silc_schedule_task_add function to add fd task.
407 #define silc_schedule_task_add_fd(schedule, fd, callback, context) \
408 silc_schedule_task_add(schedule, fd, callback, context, 0, 0, SILC_TASK_FD)
410 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_timeout
415 * silc_schedule_task_add_timeout(SilcSchedule schedule,
416 * SilcTaskCallback callback, void *context,
417 * long seconds, long useconds);
421 * A convenience function to add timeout task. You may use this if
422 * you don't want to use the silc_schedule_task_add function to add
426 #define silc_schedule_task_add_timeout(schedule, callback, context, s, u) \
427 silc_schedule_task_add(schedule, 0, callback, context, s, u, \
430 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
434 * void silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
438 * Deletes the `task' from the scheduler indicated by the `schedule'.
439 * After deleting the task it is guaranteed that the task callback
440 * will not be called. If the `task' is SILC_ALL_TASKS then all
441 * tasks is removed from the scheduler.
443 * It is safe to call this function in any place. Tasks may be removed
444 * in task callbacks (including in the task's own task callback) and
445 * in multi-threaded environment in other threads as well.
448 void silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
450 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd
454 * void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
458 * Deletes a task from the scheduler by the specified `fd'.
460 * It is safe to call this function in any place. Tasks may be removed
461 * in task callbacks (including in the task's own task callback) and
462 * in multi-threaded environment in other threads as well.
465 void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
467 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
471 * void silc_schedule_task_del_by_callback(SilcSchedule schedule,
472 * SilcTaskCallback callback);
476 * Deletes a task from the scheduler by the specified `callback' task
479 * It is safe to call this function in any place. Tasks may be removed
480 * in task callbacks (including in the task's own task callback) and
481 * in multi-threaded environment in other threads as well.
484 void silc_schedule_task_del_by_callback(SilcSchedule schedule,
485 SilcTaskCallback callback);
487 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context
491 * void silc_schedule_task_del_by_context(SilcSchedule schedule,
496 * Deletes a task from the scheduler by the specified `context'.
498 * It is safe to call this function in any place. Tasks may be removed
499 * in task callbacks (including in the task's own task callback) and
500 * in multi-threaded environment in other threads as well.
503 void silc_schedule_task_del_by_context(SilcSchedule schedule, void *context);
505 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_all
509 * void silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
510 * SilcTaskCallback callback,
515 * Deletes a task from the scheduler by the specified `fd', `callback'
518 * It is safe to call this function in any place. Tasks may be removed
519 * in task callbacks (including in the task's own task callback) and
520 * in multi-threaded environment in other threads as well.
523 void silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
524 SilcTaskCallback callback, void *context);
526 /****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
530 * void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
531 * SilcTaskEvent mask, bool send_events);
535 * Sets a file descriptor `fd' to be listened by the scheduler for
536 * `mask' events. To tell scheduler not to listen anymore for this
537 * file descriptor call the silc_schedule_unset_listen_fd function.
538 * When new task is created with silc_schedule_task_add the event
539 * for the task's fd is initially set to SILC_TASK_READ. If you need
540 * to control the task's fd's events you must call this function
541 * whenever you need to change the events. This can be called multiple
542 * times to change the events.
544 * If the `send_events' is TRUE then this function sends the events
545 * in `mask' to the application. If FALSE then they are sent only
546 * after the event occurs in reality. In normal cases the `send_events'
550 void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
551 SilcTaskEvent mask, bool send_events);
553 /****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
557 * void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
561 * Tells the scheduler not to listen anymore for the specified
562 * file descriptor `fd'. No events will be detected for the `fd'
563 * after calling this function.
566 void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
568 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_register
572 * void silc_schedule_signal_register(SilcSchedule schedule,
574 * SilcTaskCallback callback,
579 * Register signal indicated by `signal' to the scheduler. Application
580 * should register all signals it is going to use to the scheduler.
581 * The `callback' with `context' will be called after the application
582 * has called silc_schedule_signal_call function in the real signal
583 * callback. Application is responsible of calling that, and the
584 * signal system will not work without calling silc_schedule_signal_call
585 * function. The specified `signal' value will be also delivered to
586 * the `callback' as the fd-argument. The event type in the callback
587 * will be SILC_TASK_INTERRUPT. It is safe to use any SILC routines
588 * in the `callback' since it is actually called after the signal really
591 * On platform that does not support signals calling this function has
596 * Typical signal usage case on Unix systems:
598 * struct sigaction sa;
599 * sa.sa_handler = signal_handler;
600 * sigaction(SIGHUP, &sa, NULL);
601 * sigaction(SIGINT, &sa, NULL);
602 * silc_schedule_signal_register(schedule, SIGHUP, hup_signal, context);
603 * silc_schedule_signal_register(schedule, SIGINT, int_signal, context);
605 * static void signal_handler(int sig)
607 * silc_schedule_signal_call(schedule, sig);
610 * The `signal_handler' can be used as generic signal callback in the
611 * application that merely calls silc_schedule_signal_call, which then
612 * eventually will deliver for example the `hup_signal' callback. The
613 * same `signal_handler' can be used with all signals.
616 void silc_schedule_signal_register(SilcSchedule schedule, SilcUInt32 signal,
617 SilcTaskCallback callback, void *context);
619 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_unregister
623 * void silc_schedule_signal_unregister(SilcSchedule schedule,
625 * SilcTaskCallback callback,
630 * Unregister a signal indicated by `signal' from the scheduler. On
631 * platform that does not support signals calling this function has no
635 void silc_schedule_signal_unregister(SilcSchedule schedule, SilcUInt32 signal,
636 SilcTaskCallback callback, void *context);
638 /****f* silcutil/SilcScheduleAPI/silc_schedule_signal_call
642 * void silc_schedule_signal_call(SilcSchedule schedule,
643 * SilcUInt32 signal);
647 * Mark the `signal' to be called later. Every signal that has been
648 * registered by silc_schedule_signal_register is delivered by calling
649 * this function. When signal really occurs, the application is
650 * responsible of calling this function in the signal handler. After
651 * signal is over the scheduler will then safely deliver the callback
652 * that was given to silc_schedule_signal_register function.
655 void silc_schedule_signal_call(SilcSchedule schedule, SilcUInt32 signal);
657 #include "silcschedule_i.h"