5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1998 - 2007 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/SilcTaskEvent
102 * typedef enum { ... } SilcTaskEvent;
106 * SILC Task event types. The event type indicates the occurred
107 * event of the task. This type will be given as argument to the
108 * SilcTaskCallback function to indicate the event for the caller.
109 * The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller
110 * of the silc_schedule_set_listen_fd, if the caller needs to control
111 * the events for the task. The SILC_TASK_EXPIRE is set always only
112 * by the scheduler when timeout expires for timeout task. The
113 * SILC_TASK_INTERRUPT is set for signal callback.
118 SILC_TASK_READ = 0x0001, /* Reading */
119 SILC_TASK_WRITE = 0x0002, /* Writing */
120 SILC_TASK_EXPIRE = 0x0004, /* Timeout */
121 SILC_TASK_INTERRUPT = 0x0008, /* Signal */
125 /****f* silcutil/SilcScheduleAPI/SilcTaskCallback
129 * typedef void (*SilcTaskCallback)(SilcSchedule schedule,
131 * SilcTaskEvent type, SilcUInt32 fd,
136 * The task callback function. This function will be called by the
137 * scheduler when some event of the task is performed. For example,
138 * when data is available from the connection this will be called.
140 * The `schedule' is the scheduler context, the `type' is the indicated
141 * event, the `fd' is the file descriptor of the task and the `context'
142 * is a caller specified context. If multiple events occurred this
143 * callback is called separately for all events. The `app_context'
144 * is application specific context that was given as argument to the
145 * silc_schedule_init function. If the task is timeout task then `fd'
148 * To specify task callback function in the application using the
149 * SILC_TASK_CALLBACK macro is recommended.
151 * The callback should not perform lenghty or blocking operations as
152 * this would also block all other waiting tasks. The task callback
153 * should either handle the operation fast or issue an asynchronous
154 * call (like to register 0 timeout task) to handle it later.
157 typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context,
158 SilcTaskEvent type, SilcUInt32 fd,
163 /****d* silcutil/SilcScheduleAPI/SILC_ALL_TASKS
167 * #define SILC_ALL_TASKS ...
171 * Marks for all tasks in the scheduler. This can be passed to
172 * silc_schedule_task_del function to delete all tasks at once.
176 #define SILC_ALL_TASKS ((SilcTask)1)
179 /****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
183 * #define SILC_TASK_CALLBACK ...
187 * Generic macro to define task callback functions. This defines a
188 * static function with name `func' as a task callback function.
192 #define SILC_TASK_CALLBACK(func) \
193 void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \
194 SilcUInt32 fd, void *context)
199 #include "silcschedule_i.h"
201 /****f* silcutil/SilcScheduleAPI/silc_schedule_init
205 * SilcSchedule silc_schedule_init(int max_tasks, void *app_context);
209 * Initializes the scheduler. This returns the scheduler context that
210 * is given as argument usually to all silc_schedule_* functions.
211 * The `app_context' is application specific context that is delivered
212 * to all task callbacks. The caller must free that context. The
213 * 'app_context' can be for example the application itself.
215 * The `max_tasks' is the maximum number of file descriptor and socket
216 * tasks in the scheduler. Set value to 0 to use default. Operating
217 * system will enforce the final limit. On some operating systems the
218 * limit can be significantly increased when this function is called in
219 * priviliged mode (as super user).
222 SilcSchedule silc_schedule_init(int max_tasks, void *app_context);
224 /****f* silcutil/SilcScheduleAPI/silc_schedule_uninit
228 * SilcBool silc_schedule_uninit(SilcSchedule schedule);
232 * Uninitializes the scheduler. This is called when the program is ready
233 * to end. This removes all tasks from the scheduler. Returns FALSE if the
234 * scheduler could not be uninitialized. This happens when the scheduler
235 * is still valid and silc_schedule_stop has not been called.
238 SilcBool silc_schedule_uninit(SilcSchedule schedule);
240 /****f* silcutil/SilcScheduleAPI/silc_schedule_stop
244 * void silc_schedule_stop(SilcSchedule schedule);
248 * Stops the scheduler even if it is not supposed to be stopped yet.
249 * After calling this, one must call silc_schedule_uninit (after the
250 * silc_schedule has returned). After this is called it is guaranteed
251 * that next time the scheduler enters the main loop it will be stopped.
252 * However, untill it enters the main loop it will not detect that
253 * it is stopped for example if this is called from another thread.
256 void silc_schedule_stop(SilcSchedule schedule);
258 /****f* silcutil/SilcScheduleAPI/silc_schedule
262 * void silc_schedule(SilcSchedule schedule);
266 * The SILC scheduler. The program will run inside this function.
267 * When this returns the program is to be ended. Before this function can
268 * be called, one must call silc_schedule_init function.
272 * On Windows this will block the program, but will continue dispatching
273 * window messages, and thus can be used as the main loop of the program.
275 * On Symbian this will return immediately. On Symbian calling
276 * silc_schedule is same as calling silc_schedule_one. This also means
277 * the caller must be already running Symbian Active Scheduler.
280 void silc_schedule(SilcSchedule schedule);
282 /****f* silcutil/SilcScheduleAPI/silc_schedule_one
286 * SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
290 * Same as the silc_schedule but runs the scheduler only one round
291 * and then returns. This function is handy when the SILC scheduler
292 * is used inside some other external scheduler, for example. If
293 * the `timeout_usecs' is non-negative a timeout will be added to the
294 * scheduler. The function will not return in this timeout unless
295 * some other event occurs.
297 * Typically this would be called from a timeout or idle task
298 * periodically (typically from 5-50 ms) to schedule SILC tasks. In
299 * this case the `timeout_usecs' is usually 0 to make the function
300 * return immediately.
303 SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
305 /****f* silcutil/SilcScheduleAPI/silc_schedule_wakeup
309 * void silc_schedule_wakeup(SilcSchedule schedule);
313 * Wakes up the scheduler. This is may be used in multi-threaded
314 * environments where threads may add new tasks or remove old tasks
315 * from the scheduler. This is called to wake up the scheduler in the
316 * main thread so that it detects the changes in the scheduler.
317 * If threads support is not compiled in this function has no effect.
320 void silc_schedule_wakeup(SilcSchedule schedule);
322 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_context
326 * void *silc_schedule_get_context(SilcSchedule schedule);
330 * Returns the application specific context that was saved into the
331 * scheduler in silc_schedule_init function. The context is also
332 * returned to application in the SilcTaskCallback, but this function
333 * may be used to get it as well if needed.
336 void *silc_schedule_get_context(SilcSchedule schedule);
338 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_fd
343 * silc_schedule_task_add_fd(SilcSchedule schedule, SilcUInt32 fd,
344 * SilcTaskCallback callback, void *context);
348 * Add file descriptor task to scheduler. The `fd' may be either real
349 * file descriptor, socket or on some platforms an opaque file descriptor
350 * handle. To receive events for the file descriptor set the correct
351 * request events with silc_schedule_set_listen_fd function.
353 * The task will be initially set for SILC_TASK_READ events. Setting that
354 * event immediately after this call returns is not necessary.
356 * This returns the new task or NULL on error. If a task with `fd' has
357 * already been added this will return the existing task pointer.
360 #define silc_schedule_task_add_fd(schedule, fd, callback, context) \
361 silc_schedule_task_add(schedule, fd, callback, context, 0, 0, SILC_TASK_FD)
363 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_timeout
368 * silc_schedule_task_add_timeout(SilcSchedule schedule,
369 * SilcTaskCallback callback, void *context,
370 * long seconds, long useconds);
374 * Add timeout task to scheduler. The `callback' will be called once
375 * the specified timeout has elapsed. The task will be removed from the
376 * scheduler automatically once the task expires. The event returned
377 * to the `callback' is SILC_TASK_EXPIRE. The task added with zero (0)
378 * timeout will be executed immediately next time tasks are scheduled.
381 #define silc_schedule_task_add_timeout(schedule, callback, context, s, u) \
382 silc_schedule_task_add(schedule, 0, callback, context, s, u, \
385 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_signal
390 * silc_schedule_task_add_signal(SilcSchedule schedule, int signal,
391 * SilcTaskCallback callback, void *context);
395 * Add platform specific process signal handler to scheduler. On Unix
396 * systems the `signal' is one of the signal specified in signal(7). On
397 * other platforms this function may not be available at all, and has no
398 * effect when called. The event delivered to the `callback' is
399 * SILC_TASK_INTERRUPT.
403 * One signal may be registered only one callback. Adding second callback
404 * for signal that already has one will fail.
406 * This function always returns NULL. To remove signal from scheduler by
407 * the signal call silc_schedule_task_del_by_fd.
410 #define silc_schedule_task_add_signal(schedule, sig, callback, context) \
411 silc_schedule_task_add(schedule, sig, callback, context, 0, 0, \
414 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
418 * SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
422 * Deletes the `task' from the scheduler indicated by the `schedule'.
423 * After deleting the task it is guaranteed that the task callback
424 * will not be called. If the `task' is SILC_ALL_TASKS then all
425 * tasks is removed from the scheduler. Returns always TRUE.
427 * It is safe to call this function in any place. Tasks may be removed
428 * in task callbacks (including in the task's own task callback) and
429 * in multi-threaded environment in other threads as well.
432 SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
434 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_fd
438 * SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule,
443 * Deletes a task from the scheduler by the specified `fd'. Returns
444 * FALSE if such fd task does not exist.
446 * It is safe to call this function in any place. Tasks may be removed
447 * in task callbacks (including in the task's own task callback) and
448 * in multi-threaded environment in other threads as well.
451 SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
453 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
457 * SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
458 * SilcTaskCallback callback);
462 * Deletes a task from the scheduler by the specified `callback' task
463 * callback function. Returns FALSE if such task with such callback
466 * It is safe to call this function in any place. Tasks may be removed
467 * in task callbacks (including in the task's own task callback) and
468 * in multi-threaded environment in other threads as well.
471 SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
472 SilcTaskCallback callback);
474 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_context
478 * SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
483 * Deletes a task from the scheduler by the specified `context'. Returns
484 * FALSE if such task with such context does not exist.
486 * It is safe to call this function in any place. Tasks may be removed
487 * in task callbacks (including in the task's own task callback) and
488 * in multi-threaded environment in other threads as well.
491 SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
494 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_all
498 * SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
499 * SilcTaskCallback callback,
504 * Deletes a task from the scheduler by the specified `fd', `callback'
505 * and `context'. Returns FALSE if such task does not exist.
507 * It is safe to call this function in any place. Tasks may be removed
508 * in task callbacks (including in the task's own task callback) and
509 * in multi-threaded environment in other threads as well.
512 SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
513 SilcTaskCallback callback,
516 /****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd
520 * SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule,
522 * SilcTaskEvent mask,
523 * SilcBool send_events);
527 * Sets a file descriptor `fd' to be listened by the scheduler for
528 * `mask' events. To tell scheduler not to listen anymore for this
529 * file descriptor call the silc_schedule_unset_listen_fd function.
530 * When new task is created with silc_schedule_task_add the event
531 * for the task's fd is initially set to SILC_TASK_READ. If you need
532 * to control the task's fd's events you must call this function
533 * whenever you need to change the events. This can be called multiple
534 * times to change the events.
536 * If the `send_events' is TRUE then this function sends the events
537 * in `mask' to the application. If FALSE then they are sent only
538 * after the event occurs in reality. In normal cases the `send_events'
541 * Returns FALSE if the operation could not performed and TRUE if it
545 SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
546 SilcTaskEvent mask, SilcBool send_events);
548 /****f* silcutil/SilcScheduleAPI/silc_schedule_get_fd_events
552 * SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
557 * Returns the file descriptor `fd' current requested events mask,
561 SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
564 /****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
568 * void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
572 * Tells the scheduler not to listen anymore for the specified
573 * file descriptor `fd'. No events will be detected for the `fd'
574 * after calling this function.
577 void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);