5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1998 - 2008 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/Scheduler 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, timeout tasks and
29 * asynchronous event tasks. File descriptor tasks are tasks that perform
30 * some operation over the specified file descriptor or socket. The timeout
31 * tasks are timeouts that are executed after the specified timeout has
32 * elapsed. Asynchronous event tasks are tasks that can be connected to
33 * and signalled to deliver messages and data to all connected entities.
35 * The SILC Scheduler is designed to be the sole main loop of the application
36 * so that the application does not need any other main loop. However,
37 * SILC Scheduler does support running the scheduler only one iteration, so
38 * that the scheduler does not block, and thus providing a possiblity that some
39 * external main loop is run over the SILC Scheduler.
41 * On Windows systems the SILC Scheduler is too designed to work as the main
42 * loop of the GUI application. It can handle all Windows messages and
43 * it dispatches them from the scheduler, and thus makes it possible to
44 * create GUI applications. The scheduler can also handle all kinds of
45 * WIN32 handles, this includes sockets created by the SILC Net API routines,
46 * WSAEVENT handle objects created by Winsock2 routines and arbitrary
47 * WIN32 HANDLE objects.
49 * On Symbian OS the SILC Scheduler can work in cooperation with the Active
50 * Scheduler. However, the Symbian OS Active Scheduler must be started
51 * before starting SILC Scheduler.
53 * The SILC Scheduler supports multi-threads. Each thread can have their
54 * own scheduler. Tasks registered to a scheduler are always executed in
55 * that same thread. However, tasks may be added to and removed from any
56 * scheduler from any thread. Each scheduler in worker thread should be
57 * a child scheduler created from the main thread's parent scheduler.
61 #ifndef SILCSCHEDULE_H
62 #define SILCSCHEDULE_H
64 /****s* silcutil/SilcSchedule
68 * typedef struct SilcScheduleStruct *SilcSchedule;
72 * This context is the actual Scheduler and is allocated by
73 * the silc_schedule_init funtion. The context is given as argument
74 * to all silc_schedule_* functions. It must be freed by the
75 * silc_schedule_uninit function.
78 typedef struct SilcScheduleStruct *SilcSchedule;
80 /****s* silcutil/SilcTask
84 * typedef struct SilcTaskStruct *SilcTask;
88 * This object represents one task in the scheduler. It is allocated
89 * by the silc_schedule_task_add function and freed by one of the
90 * silc_schedule_task_del* functions.
93 typedef struct SilcTaskStruct *SilcTask;
95 /****d* silcutil/SilcTaskEvent
99 * typedef enum { ... } SilcTaskEvent;
103 * SILC Task event types. The event type indicates the occurred
104 * event of the task. This type will be given as argument to the
105 * SilcTaskCallback function to indicate the event for the caller.
106 * The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller
107 * of the silc_schedule_set_listen_fd, if the caller needs to control
108 * the events for the task. The SILC_TASK_EXPIRE is set always only
109 * by the scheduler when timeout expires for timeout task. The
110 * SILC_TASK_INTERRUPT is set for signal callback.
115 SILC_TASK_READ = 0x0001, /* Reading */
116 SILC_TASK_WRITE = 0x0002, /* Writing */
117 SILC_TASK_EXPIRE = 0x0004, /* Timeout */
118 SILC_TASK_INTERRUPT = 0x0008, /* Signal */
122 /****f* silcutil/SilcTaskCallback
126 * typedef void (*SilcTaskCallback)(SilcSchedule schedule,
128 * SilcTaskEvent type, SilcUInt32 fd,
133 * The task callback function. This function will be called by the
134 * scheduler when some event of the task is performed. For example,
135 * when data is available from the connection this will be called.
137 * The `schedule' is the scheduler context, the `type' is the indicated
138 * event, the `fd' is the file descriptor of the task and the `context'
139 * is a caller specified context. If multiple events occurred this
140 * callback is called separately for all events. The `app_context'
141 * is application specific context that was given as argument to the
142 * silc_schedule_init function. If the task is timeout task then `fd'
145 * To specify task callback function in the application using the
146 * SILC_TASK_CALLBACK macro is recommended.
148 * The callback should not perform lenghty or blocking operations as
149 * this would also block all other waiting tasks. The task callback
150 * should either handle the operation fast or issue an asynchronous
151 * call (like to register 0 timeout task) to handle it later.
154 typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context,
155 SilcTaskEvent type, SilcUInt32 fd,
158 /****f* silcutil/SilcTaskEventCallback
162 * typedef void (*SilcTaskEventCallback)(SilcSchedule schedule,
164 * SilcTask task, void *context,
169 * Task callback for event tasks added with silc_schedule_task_add_event.
170 * The callback of this type is called when an event task is signalled.
171 * The signal is delivered to all that have connected to the event.
173 * The `task' is the event task. The `context' is the context given as
174 * argument to silc_schedule_event_connect. The `schedule' is the
175 * scheduler given as argument to silc_schedule_event_connect.
177 * If FALSE is returned in this callback function the signal delivery to
178 * other connected entities is stopped. Normally, TRUE is returned.
179 * If the `task' is deleted in this callback, the signal delivery is also
182 * To specify task event callback function in the application using the
183 * SILC_TASK_EVENT_CALLBACK macro is recommended.
186 typedef SilcBool (*SilcTaskEventCallback)(SilcSchedule schedule,
188 SilcTask task, void *context,
191 /****f* silcutil/SilcTaskNotifyCb
195 * typedef void (*SilcTaskNotifyCb)(SilcSchedule schedule,
196 * SilcBool added, SilcTask task,
197 * SilcBool fd_task, SilcUInt32 fd,
198 * SilcTaskEvent event,
199 * long seconds, long useconds,
204 * Task notify callback. Callback of this type can be set to scheduler
205 * by calling silc_schedule_set_notify and will be called whenever new
206 * task is added or old task is removed. If `added' is TRUE then `task'
207 * is added to scheduler. If `added' is FALSE then `task' will be removed
208 * from the scheduler. If `fd_task' is TRUE the `task' is file descriptor
209 * task and has `fd' is its file descriptor. If `fd_task' is FALSE then
210 * the task is timeout task and `seconds' and `useconds' specify the
211 * timeout. The `context' is the context given to silc_schedule_set_notify.
215 * The `schedule' is locked while this callback is called. This means that
216 * new tasks cannot be added or removed inside this callback.
218 * When timeout task expires this callback is not called. This is called
219 * only when task is explicitly deleted from the scheduler. Note that,
220 * when timeout task expires it is removed from the scheduler and `task'
221 * will become invalid.
223 * If fd task changes its events, this will be called as if it was a new
224 * task with different `event' mask.
227 typedef void (*SilcTaskNotifyCb)(SilcSchedule schedule,
228 SilcBool added, SilcTask task,
229 SilcBool fd_task, SilcUInt32 fd,
231 long seconds, long useconds,
236 /****d* silcutil/SILC_ALL_TASKS
240 * #define SILC_ALL_TASKS ...
244 * Marks for all tasks in the scheduler. This can be passed to
245 * silc_schedule_task_del function to delete all tasks at once.
249 #define SILC_ALL_TASKS ((SilcTask)1)
252 /****d* silcutil/SILC_TASK_CALLBACK
256 * #define SILC_TASK_CALLBACK ...
260 * Generic macro to declare task callback functions. This defines a
261 * function with name `func' as a task callback function.
265 #define SILC_TASK_CALLBACK(func) \
266 void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \
267 SilcUInt32 fd, void *context)
270 /****d* silcutil/SILC_TASK_EVENT_CALLBACK
274 * #define SILC_TASK_EVENT_CALLBACK ...
278 * Generic macro to declare event task callback functions. This defines a
279 * function with name `func' as a event task callback function.
283 #define SILC_TASK_EVENT_CALLBACK(func) \
284 SilcBool func(SilcSchedule schedule, void *app_context, \
285 SilcTask task, void *context, va_list va)
291 #include "silcschedule_i.h"
293 /****f* silcutil/silc_schedule_init
297 * SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
298 * SilcStack stack, SilcSchedule parent);
302 * Initializes the scheduler. This returns the scheduler context or NULL
303 * on error. The `app_context' is application specific context that is
304 * delivered to all task callbacks. The caller must free that context.
306 * The `max_tasks' is the maximum number of file descriptor and socket
307 * tasks in the scheduler. Set value to 0 to use default. Operating
308 * system will enforce the final limit. On some operating systems the
309 * limit can be significantly increased when this function is called in
310 * priviliged mode (as super user).
312 * If `parent' is non-NULL it will be the parent of the new scheduler.
313 * If it is NULL this will create a new parent scheduler. If `parent'
314 * is already a child scheduler, this will create a new child to the
315 * child's parent. Even if `parent' is non-NULL the new child scheduler
316 * is still independent scheduler and will run independently of its
317 * parent. However, each child and parent will share event tasks
318 * added with silc_schedule_task_add_event.
320 * If `stack' is non-NULL all memory allocation for the scheduler is done
321 * from the `stack'. Scheduler's stack may be retrieved by calling
322 * silc_schedule_get_stack. A stack is created for scheduler always even
323 * if `stack' is NULL. If it is non-NULL the created stack is a child
324 * stack using `stack' as its parent. This means that memory allocated
325 * by the scheduler will be returned to the `stack' when scheduler is
329 SilcSchedule silc_schedule_init(int max_tasks, void *app_context,
330 SilcStack stack, SilcSchedule parent);
332 /****f* silcutil/silc_schedule_uninit
336 * SilcBool silc_schedule_uninit(SilcSchedule schedule);
340 * Uninitializes the scheduler. This is called when the program is ready
341 * to end. This removes all tasks from the scheduler. Returns FALSE if the
342 * scheduler could not be uninitialized. This happens when the scheduler
343 * is still valid and silc_schedule_stop has not been called.
345 * If SilcStack was given to silc_schedule_init all memory allocated
346 * during the life time of the scheduler will be returned back to the
350 SilcBool silc_schedule_uninit(SilcSchedule schedule);
352 /****f* silcutil/silc_schedule_stop
356 * void silc_schedule_stop(SilcSchedule schedule);
360 * Stops the scheduler even if it is not supposed to be stopped yet.
361 * After calling this, one must call silc_schedule_uninit (after the
362 * silc_schedule has returned). After this is called it is guaranteed
363 * that next time the scheduler enters the main loop it will be stopped.
364 * However, untill it enters the main loop it will not detect that
365 * it is stopped for example if this is called from another thread.
368 void silc_schedule_stop(SilcSchedule schedule);
370 /****f* silcutil/silc_schedule
374 * void silc_schedule(SilcSchedule schedule);
378 * The SILC scheduler. The program will run inside this function.
379 * When this returns the program is to be ended. Before this function
380 * can be called, one must call silc_schedule_init function.
384 * On Windows this will block the calling thread but will continue
385 * to dispatch window messages, and thus can be used as the main loop
388 * On Symbian this will block the calling thread. The Symbian Active
389 * Scheduler must be running before calling this function.
392 void silc_schedule(SilcSchedule schedule);
394 /****f* silcutil/silc_schedule_one
398 * SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
402 * Same as the silc_schedule but runs the scheduler only one round
403 * and then returns. This function is handy when the SILC scheduler
404 * is used inside some other external scheduler, for example. If
405 * the `timeout_usecs' is non-negative a timeout will be added to the
406 * scheduler. The function will not return in this timeout unless
407 * some other event occurs.
409 * Typically this would be called from a timeout or idle task
410 * periodically (typically from 5-50 ms) to schedule SILC tasks. In
411 * this case the `timeout_usecs' is usually 0 to make the function
412 * return immediately.
415 SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
417 /****f* silcutil/silc_schedule_wakeup
421 * void silc_schedule_wakeup(SilcSchedule schedule);
425 * Wakes up the scheduler. This is may be used in multi-threaded
426 * environments where threads may add new tasks or remove old tasks
427 * from the scheduler. This is called to wake up the scheduler in the
428 * main thread so that it detects the changes in the scheduler.
429 * If threads support is not compiled in this function has no effect.
432 void silc_schedule_wakeup(SilcSchedule schedule);
434 /****f* silcutil/silc_schedule_get_parent
438 * SilcSchedule silc_schedule_get_parent(SilcSchedule schedule);
442 * Returns the parent scheduler of the `schedule'. Never returns NULL.
445 SilcSchedule silc_schedule_get_parent(SilcSchedule schedule);
447 /****f* silcutil/silc_schedule_get_context
451 * void *silc_schedule_get_context(SilcSchedule schedule);
455 * Returns the application specific context that was saved into the
456 * scheduler in silc_schedule_init function. The context is also
457 * returned to application in the SilcTaskCallback, but this function
458 * may be used to get it as well if needed.
461 void *silc_schedule_get_context(SilcSchedule schedule);
463 /****f* silcutil/silc_schedule_get_stack
467 * SilcStack silc_schedule_get_stack(SilcSchedule schedule);
471 * Returns the stack of the `schedule'. If it is used to make memory
472 * allocations outside the scheduler, it is recommended that a new
473 * child stack is created by using the returned stack as a parent and
474 * using the child stack to make the memory allocations.
477 SilcStack silc_schedule_get_stack(SilcSchedule schedule);
479 /****f* silcutil/silc_schedule_set_notify
483 * void silc_schedule_set_notify(SilcSchedule schedule,
484 * SilcTaskNotifyCb notify, void *context);
488 * Set notify callback to scheduler. The `notify' will be called whenever
489 * task is added to or deleted from scheduler.
492 void silc_schedule_set_notify(SilcSchedule schedule,
493 SilcTaskNotifyCb notify, void *context);
495 /****f* silcutil/silc_schedule_set_global
499 * void silc_schedule_set_global(SilcSchedule schedule);
503 * Sets global SilcSchedule `schedule' that can be retrieved at any time
504 * by using silc_schedule_get_global. The global scheduler is global only
505 * to the current thread. Each thread can have their own global scheduler.
506 * If each thread must have global scheduler this must be called in each
507 * thread. If the global scheduler has been set already, new call will
508 * replace the old one.
510 * This routine is provided only as a convenience function to store
511 * program's or thread's scheduler in one global place. It is not mandatory
512 * to call this function in order to use SilcSchedule.
514 * Many routines that require SilcSchedule as an argument will call
515 * silc_schedule_get_global if the scheduler is not provided to try to
516 * get global scheduler. Almost all routines in SilcSchedule API will call
517 * silc_schedule_get_global if the SilcSchedule is not provided as argument.
520 void silc_schedule_set_global(SilcSchedule schedule);
522 /****f* silcutil/silc_schedule_get_global
526 * SilcSchedule silc_schedule_get_global(void);
530 * Returns the thread's global scheduler that was set by calling
531 * silc_schedule_set_global or NULL if global scheduler has not been set.
534 SilcSchedule silc_schedule_get_global(void);
536 /****f* silcutil/silc_schedule_task_add_fd
541 * silc_schedule_task_add_fd(SilcSchedule schedule, SilcUInt32 fd,
542 * SilcTaskCallback callback, void *context);
546 * Add file descriptor task to scheduler. The `fd' may be either real
547 * file descriptor, socket or on some platforms an opaque file descriptor
548 * handle. To receive events for the file descriptor set the correct
549 * request events with silc_schedule_set_listen_fd function.
551 * The task will be initially set for SILC_TASK_READ events. Setting that
552 * event immediately after this call returns is not necessary.
554 * This returns the new task or NULL on error. If a task with `fd' has
555 * already been added this will return the existing task pointer.
557 * If `schedule' is NULL this will call silc_schedule_get_global to try to
558 * get global scheduler.
561 #define silc_schedule_task_add_fd(schedule, fd, callback, context) \
562 silc_schedule_task_add(schedule, fd, callback, context, 0, 0, SILC_TASK_FD)
564 /****f* silcutil/silc_schedule_task_add_timeout
569 * silc_schedule_task_add_timeout(SilcSchedule schedule,
570 * SilcTaskCallback callback, void *context,
571 * long seconds, long useconds);
575 * Add timeout task to scheduler. The `callback' will be called once
576 * the specified timeout has elapsed. The task will be removed from the
577 * scheduler automatically once the task expires. The event returned
578 * to the `callback' is SILC_TASK_EXPIRE. A task added with zero (0)
579 * timeout will be executed immediately next time tasks are scheduled.
581 * If `schedule' is NULL this will call silc_schedule_get_global to try to
582 * get global scheduler.
585 #define silc_schedule_task_add_timeout(schedule, callback, context, s, u) \
586 silc_schedule_task_add(schedule, 0, callback, context, s, u, \
589 /****f* silcutil/silc_schedule_task_add_signal
594 * silc_schedule_task_add_signal(SilcSchedule schedule, int signal,
595 * SilcTaskCallback callback, void *context);
599 * Add platform specific process signal handler to scheduler. On Unix
600 * systems the `signal' is one of the signal specified in signal(7). On
601 * other platforms this function may not be available at all, and has no
602 * effect when called. The event delivered to the `callback' is
603 * SILC_TASK_INTERRUPT.
605 * If `schedule' is NULL this will call silc_schedule_get_global to try to
606 * get global scheduler.
610 * One signal may be registered only one callback. Adding second callback
611 * for signal that already has one will fail.
613 * This function always returns NULL. To remove signal from scheduler by
614 * the signal call silc_schedule_task_del_by_fd.
617 #define silc_schedule_task_add_signal(schedule, sig, callback, context) \
618 silc_schedule_task_add(schedule, sig, callback, context, 0, 0, \
621 /****f* silcutil/silc_schedule_task_add_event
626 * silc_schedule_task_add_event(SilcSchedule schedule,
627 * const char *event, ...);
631 * Adds an event task to scheduler. These tasks are asynchronous events
632 * that one or more receivers may connect to and receive information or
633 * data when the event is signalled. Event tasks are fast and may be
634 * used to efficiently deliver events and data to multiple receivers. The
635 * `event' is the name of the event, and can be used to connect to the
636 * event and to signal it.
638 * The events are global among the `scheduler', its parent scheduler and
639 * any of its child schedulers. It does not matter to which scheduler
640 * event is added to, connected to or signalled. Signal will reach any
641 * connected entity, as long as it is the parent or one of the fellow
642 * children of `schedule'.
644 * To connect to an event call silc_schedule_event_connect.
645 * To disconnect from event call silc_schedule_event_disconnect.
646 * To signal event call silc_schedule_event_signal.
647 * To delete event task call silc_schedule_task_del or
648 * silc_schedule_task_del_event.
650 * The variable argument list is used to describe the arguments of the
651 * event. The variable arguments are a list of zero or more SilcParam
652 * values. The list must be ended with SILC_PARAM_END. This function
653 * returns the event task context or NULL on error.
657 * // Register 'connected' event
658 * silc_schedule_task_add_event(schedule, "connected",
663 * // Connect to 'connected' event
664 * silc_schedule_event_connect(schedule, "connected", NULL,
665 * connected_cb, ctx);
667 * // Signal 'connected' event
668 * silc_schedule_event_signal(schedule, "connected", NULL, integer, buf);
670 * // 'connected' event handler
671 * SILC_TASK_CALLBACK(connected_cb)
673 * FooCtx ctx = context;
674 * SilcUInt32 integer;
677 * integer = va_arg(va, SilcUInt32);
678 * buf = va_arg(va, SilcBuffer);
683 SilcTask silc_schedule_task_add_event(SilcSchedule schedule,
684 const char *event, ...);
686 /****f* silcutil/silc_schedule_task_del
690 * SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
694 * Deletes the `task' from the scheduler indicated by the `schedule'.
695 * After deleting the task it is guaranteed that the task callback
696 * will not be called. If the `task' is SILC_ALL_TASKS then all
697 * tasks is removed from the scheduler. Returns always TRUE.
699 * It is safe to call this function in any place. Tasks may be removed
700 * in task callbacks (including in the task's own task callback) and
701 * in multi-threaded environment in other threads as well.
703 * If `schedule' is NULL this will call silc_schedule_get_global to try to
704 * get global scheduler.
707 SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task);
709 /****f* silcutil/silc_schedule_task_del_by_fd
713 * SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule,
718 * Deletes a task from the scheduler by the specified `fd'. Returns
719 * FALSE if such fd task does not exist.
721 * It is safe to call this function in any place. Tasks may be removed
722 * in task callbacks (including in the task's own task callback) and
723 * in multi-threaded environment in other threads as well.
725 * If `schedule' is NULL this will call silc_schedule_get_global to try to
726 * get global scheduler.
729 SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
731 /****f* silcutil/silc_schedule_task_del_by_callback
735 * SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
736 * SilcTaskCallback callback);
740 * Deletes a task from the scheduler by the specified `callback' task
741 * callback function. Returns FALSE if such task with such callback
744 * It is safe to call this function in any place. Tasks may be removed
745 * in task callbacks (including in the task's own task callback) and
746 * in multi-threaded environment in other threads as well.
748 * If `schedule' is NULL this will call silc_schedule_get_global to try to
749 * get global scheduler.
752 SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule,
753 SilcTaskCallback callback);
755 /****f* silcutil/silc_schedule_task_del_by_context
759 * SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
764 * Deletes a task from the scheduler by the specified `context'. Returns
765 * FALSE if such task with such context does not exist.
767 * It is safe to call this function in any place. Tasks may be removed
768 * in task callbacks (including in the task's own task callback) and
769 * in multi-threaded environment in other threads as well.
771 * If `schedule' is NULL this will call silc_schedule_get_global to try to
772 * get global scheduler.
775 SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule,
778 /****f* silcutil/silc_schedule_task_del_by_all
782 * SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
783 * SilcTaskCallback callback,
788 * Deletes a task from the scheduler by the specified `fd', `callback'
789 * and `context'. Returns FALSE if such task does not exist.
791 * It is safe to call this function in any place. Tasks may be removed
792 * in task callbacks (including in the task's own task callback) and
793 * in multi-threaded environment in other threads as well.
795 * If `schedule' is NULL this will call silc_schedule_get_global to try to
796 * get global scheduler.
799 SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
800 SilcTaskCallback callback,
803 /****f* silcutil/silc_schedule_task_del_event
807 * void silc_schedule_task_del_event(SilcSchedule schedule,
808 * const char *event);
812 * Deletes event task by the event name `event'. Returns FALSE if the
813 * event does not exist. Events can be deleted by calling the
814 * silc_schedule_task_del also.
816 * If `schedule' is NULL this will call silc_schedule_get_global to try to
817 * get global scheduler.
820 SilcBool silc_schedule_task_del_event(SilcSchedule schedule,
823 /****f* silcutil/silc_schedule_set_listen_fd
827 * SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule,
829 * SilcTaskEvent mask,
830 * SilcBool send_events);
834 * Sets a file descriptor `fd' to be listened by the scheduler for
835 * `mask' events. To tell scheduler not to listen anymore for this
836 * file descriptor call the silc_schedule_unset_listen_fd function.
837 * When new task is created with silc_schedule_task_add the event
838 * for the task's fd is initially set to SILC_TASK_READ. If you need
839 * to control the task's fd's events you must call this function
840 * whenever you need to change the events. This can be called multiple
841 * times to change the events.
843 * If the `send_events' is TRUE then this function sends the events
844 * in `mask' to the application. If FALSE then they are sent only
845 * after the event occurs in reality. In normal cases the `send_events'
848 * If `schedule' is NULL this will call silc_schedule_get_global to try to
849 * get global scheduler.
851 * Returns FALSE if the operation could not performed and TRUE if it
855 SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
856 SilcTaskEvent mask, SilcBool send_events);
858 /****f* silcutil/silc_schedule_get_fd_events
862 * SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
867 * Returns the file descriptor `fd' current requested events mask,
870 * If `schedule' is NULL this will call silc_schedule_get_global to try to
871 * get global scheduler.
874 SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
877 /****f* silcutil/silc_schedule_unset_listen_fd
881 * void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
885 * Tells the scheduler not to listen anymore for the specified
886 * file descriptor `fd'. No events will be detected for the `fd'
887 * after calling this function.
889 * If `schedule' is NULL this will call silc_schedule_get_global to try to
890 * get global scheduler.
893 void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
895 /****f* silcutil/silc_schedule_event_connect
899 * SilcBool silc_schedule_event_connect(SilcSchedule schedule,
900 * const char *event, SilcTask task,
901 * SilcTaskEventCallback callback,
906 * Connects to an event task. The `event' or `task' must be non-NULL.
907 * If `event' is non-NULL it is the name of the event to connect to. If
908 * the `task' is non-NULL it is the event task to connect to. The event
909 * SilcTask pointer is returned by silc_schedule_task_add_event when the
910 * even is added to scheduler.
912 * The `callback' with `context' and with `schedule' are called when the
913 * even task is signalled with silc_schedule_event_signal.
915 * Returns FALSE on error or if the `callback' with `context' has already
916 * been connected. Otherwise, returns TRUE.
920 * silc_schedule_event_connect(schedule, "foo event", NULL,
921 * foo_signal_callback, foo_context);
924 SilcBool silc_schedule_event_connect(SilcSchedule schedule,
925 const char *event, SilcTask task,
926 SilcTaskEventCallback callback,
929 /****f* silcutil/silc_schedule_event_disconnect
933 * SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
934 * const char *event, SilcTask task,
935 * SilcTaskEventCallback callback,
940 * Disconnects the `callback' and `context' from an event task. The `event'
941 * or `task' must be non-NULL. If `event' is non-NULL it is the name of
942 * the event. If `task' is non-NULL it is the event task.
944 * Returns FALSE on error or if the `callback' with `context' has not been
945 * connected. Otherwise, returns TRUE.
948 SilcBool silc_schedule_event_disconnect(SilcSchedule schedule,
949 const char *event, SilcTask task,
950 SilcTaskEventCallback callback,
953 /****f* silcutil/silc_schedule_event_signal
957 * SilcBool silc_schedule_event_signal(SilcSchedule schedule,
959 * SilcTask task, ...);
963 * Signals an event task. The `event' or `task' must be non-NULL. If
964 * `event' is non-NULL it is the name of the event to signal. If the `task'
965 * is non-NULL it is the event task to be signalled. It is marginally
966 * faster to use the `task' pointer directly instead of `event' to send
969 * The variable arguments are the arguments to be sent in the signal to
970 * the connected entities. The silc_schedule_task_add_event defines what
971 * arguments must be sent to each signal. The variable argument list
972 * must not be ended with SILC_PARAM_END even though it is ended with that
973 * in silc_schedule_task_add_event.
975 * Signal delivery is synchronous; the signal is delivered inside this
976 * function. If a receiver was originally in another thread, the signal
977 * is delivered in the thread where this function is called. This means
978 * that concurrency control (locking) is required if the application uses
979 * events in multiple threads.
983 * silc_schedule_event_signal(schedule, "foo event", NULL, intarg, buffer);
986 SilcBool silc_schedule_event_signal(SilcSchedule schedule, const char *event,