X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcschedule.h;h=c3120181464b75be38a703e8c48666c7e632591c;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=8c2154a5619e405f63df48f7dc8152307922124e;hpb=52e57c880aba9c5e89f59d962eb9af75670b76e0;p=silc.git diff --git a/lib/silcutil/silcschedule.h b/lib/silcutil/silcschedule.h index 8c2154a5..c3120181 100644 --- a/lib/silcutil/silcschedule.h +++ b/lib/silcutil/silcschedule.h @@ -158,6 +158,39 @@ typedef void (*SilcTaskCallback)(SilcSchedule schedule, void *app_context, SilcTaskEvent type, SilcUInt32 fd, void *context); +/****f* silcutil/SilcScheduleAPI/SilcTaskEventCallback + * + * SYNOPSIS + * + * typedef void (*SilcTaskEventCallback)(SilcSchedule schedule, + * void *app_context, + * SilcTask task, void *context, + * va_list va); + * + * DESCRIPTION + * + * Task callback for event tasks added with silc_schedule_task_add_event. + * The callback of this type is called when an event task is signalled. + * The signal is delivered to all that have connected to the event. + * + * The `task' is the event task. The `context' is the context given as + * argument to silc_schedule_event_connect. The `schedule' is the + * scheduler given as argument to silc_schedule_event_connect. + * + * If FALSE is returned in this callback function the signal delivery to + * other connected entities is stopped. Normally, TRUE is returned. + * If the `task' is deleted in this callback, the signal delivery is also + * stopped. + * + * To specify task event callback function in the application using the + * SILC_TASK_EVENT_CALLBACK macro is recommended. + * + ***/ +typedef SilcBool (*SilcTaskEventCallback)(SilcSchedule schedule, + void *app_context, + SilcTask task, void *context, + va_list va); + /****f* silcutil/SilcScheduleAPI/SilcTaskNotifyCb * * SYNOPSIS @@ -237,6 +270,25 @@ void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \ SilcUInt32 fd, void *context) /***/ +/****d* silcutil/SilcScheduleAPI/SILC_TASK_EVENT_CALLBACK + * + * NAME + * + * #define SILC_TASK_EVENT_CALLBACK ... + * + * DESCRIPTION + * + * Generic macro to declare event task callback functions. This defines a + * function with name `func' as a event task callback function. + * + * SOURCE + */ +#define SILC_TASK_EVENT_CALLBACK(func) \ +SilcBool func(SilcSchedule schedule, void *app_context, \ + SilcTask task, void *context, va_list va) + +/***/ + /* Prototypes */ #include "silcschedule_i.h" @@ -245,15 +297,14 @@ void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \ * * SYNOPSIS * - * SilcSchedule silc_schedule_init(int max_tasks, void *app_context); + * SilcSchedule silc_schedule_init(int max_tasks, void *app_context, + * SilcStack stack, SilcSchedule parent); * * DESCRIPTION * - * Initializes the scheduler. This returns the scheduler context that - * is given as argument usually to all silc_schedule_* functions. - * The `app_context' is application specific context that is delivered - * to all task callbacks. The caller must free that context. The - * 'app_context' can be for example the application itself. + * Initializes the scheduler. This returns the scheduler context or NULL + * on error. The `app_context' is application specific context that is + * delivered to all task callbacks. The caller must free that context. * * The `max_tasks' is the maximum number of file descriptor and socket * tasks in the scheduler. Set value to 0 to use default. Operating @@ -261,8 +312,25 @@ void func(SilcSchedule schedule, void *app_context, SilcTaskEvent type, \ * limit can be significantly increased when this function is called in * priviliged mode (as super user). * + * If `parent' is non-NULL it will be the parent of the new scheduler. + * If it is NULL this will create a new parent scheduler. If `parent' + * is already a child scheduler, this will create a new child to the + * child's parent. Even if `parent' is non-NULL the new child scheduler + * is still independent scheduler and will run independently of its + * parent. However, each child and parent will share event tasks + * added with silc_schedule_task_add_event. + * + * If `stack' is non-NULL all memory allocation for the scheduler is done + * from the `stack'. Scheduler's stack may be retrieved by calling + * silc_schedule_get_stack. A stack is created for scheduler always even + * if `stack' is NULL. If it is non-NULL the created stack is a child + * stack using `stack' as its parent. This means that memory allocated + * by the scheduler will be returned to the `stack' when scheduler is + * destroyed. + * ***/ -SilcSchedule silc_schedule_init(int max_tasks, void *app_context); +SilcSchedule silc_schedule_init(int max_tasks, void *app_context, + SilcStack stack, SilcSchedule parent); /****f* silcutil/SilcScheduleAPI/silc_schedule_uninit * @@ -277,6 +345,10 @@ SilcSchedule silc_schedule_init(int max_tasks, void *app_context); * scheduler could not be uninitialized. This happens when the scheduler * is still valid and silc_schedule_stop has not been called. * + * If SilcStack was given to silc_schedule_init all memory allocated + * during the life time of the scheduler will be returned back to the + * given stack. + * ***/ SilcBool silc_schedule_uninit(SilcSchedule schedule); @@ -362,6 +434,19 @@ SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs); ***/ void silc_schedule_wakeup(SilcSchedule schedule); +/****f* silcutil/SilcScheduleAPI/silc_schedule_get_parent + * + * SYNOPSIS + * + * SilcSchedule silc_schedule_get_parent(SilcSchedule schedule); + * + * DESCRIPTION + * + * Returns the parent scheduler of the `schedule'. Never returns NULL. + * + ***/ +SilcSchedule silc_schedule_get_parent(SilcSchedule schedule); + /****f* silcutil/SilcScheduleAPI/silc_schedule_get_context * * SYNOPSIS @@ -378,6 +463,22 @@ void silc_schedule_wakeup(SilcSchedule schedule); ***/ void *silc_schedule_get_context(SilcSchedule schedule); +/****f* silcutil/SilcScheduleAPI/silc_schedule_get_stack + * + * SYNOPSIS + * + * SilcStack silc_schedule_get_stack(SilcSchedule schedule); + * + * DESCRIPTION + * + * Returns the stack of the `schedule'. If it is used to make memory + * allocations outside the scheduler, it is recommended that a new + * child stack is created by using the returned stack as a parent and + * using the child stack to make the memory allocations. + * + ***/ +SilcStack silc_schedule_get_stack(SilcSchedule schedule); + /****f* silcutil/SilcScheduleAPI/silc_schedule_set_notify * * SYNOPSIS @@ -394,6 +495,47 @@ void *silc_schedule_get_context(SilcSchedule schedule); void silc_schedule_set_notify(SilcSchedule schedule, SilcTaskNotifyCb notify, void *context); +/****f* silcutil/SilcScheduleAPI/silc_schedule_set_global + * + * SYNOPSIS + * + * void silc_schedule_set_global(SilcSchedule schedule); + * + * DESCRIPTION + * + * Sets global SilcSchedule `schedule' that can be retrieved at any time + * by using silc_schedule_get_global. The global scheduler is global only + * to the current thread. Each thread can have their own global scheduler. + * If each thread must have global scheduler this must be called in each + * thread. If the global scheduler has been set already, new call will + * replace the old one. + * + * This routine is provided only as a convenience function to store + * program's or thread's scheduler in one global place. It is not mandatory + * to call this function in order to use SilcSchedule. + * + * Many routines that require SilcSchedule as an argument will call + * silc_schedule_get_global if the scheduler is not provided to try to + * get global scheduler. Almost all routines in SilcSchedule API will call + * silc_schedule_get_global if the SilcSchedule is not provided as argument. + * + ***/ +void silc_schedule_set_global(SilcSchedule schedule); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_get_global + * + * SYNOPSIS + * + * SilcSchedule silc_schedule_get_global(void); + * + * DESCRIPTION + * + * Returns the thread's global scheduler that was set by calling + * silc_schedule_set_global or NULL if global scheduler has not been set. + * + ***/ +SilcSchedule silc_schedule_get_global(void); + /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_fd * * SYNOPSIS @@ -415,6 +557,9 @@ void silc_schedule_set_notify(SilcSchedule schedule, * This returns the new task or NULL on error. If a task with `fd' has * already been added this will return the existing task pointer. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ #define silc_schedule_task_add_fd(schedule, fd, callback, context) \ silc_schedule_task_add(schedule, fd, callback, context, 0, 0, SILC_TASK_FD) @@ -436,6 +581,9 @@ void silc_schedule_set_notify(SilcSchedule schedule, * to the `callback' is SILC_TASK_EXPIRE. A task added with zero (0) * timeout will be executed immediately next time tasks are scheduled. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ #define silc_schedule_task_add_timeout(schedule, callback, context, s, u) \ silc_schedule_task_add(schedule, 0, callback, context, s, u, \ @@ -457,6 +605,9 @@ void silc_schedule_set_notify(SilcSchedule schedule, * effect when called. The event delivered to the `callback' is * SILC_TASK_INTERRUPT. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * * NOTES * * One signal may be registered only one callback. Adding second callback @@ -470,6 +621,69 @@ void silc_schedule_set_notify(SilcSchedule schedule, silc_schedule_task_add(schedule, sig, callback, context, 0, 0, \ SILC_TASK_SIGNAL) +/****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_event + * + * SYNOPSIS + * + * SilcTask + * silc_schedule_task_add_event(SilcSchedule schedule, + * const char *event, ...); + * + * DESCRIPTION + * + * Adds an event task to scheduler. These tasks are asynchronous events + * that one or more receivers may connect to and receive information or + * data when the event is signalled. Event tasks are fast and may be + * used to efficiently deliver events and data to multiple receivers. The + * `event' is the name of the event, and can be used to connect to the + * event and to signal it. + * + * The events are global among the `scheduler', its parent scheduler and + * any of its child schedulers. It does not matter to which scheduler + * event is added to, connected to or signalled. Signal will reach any + * connected entity, as long as it is the parent or one of the fellow + * children of `schedule'. + * + * To connect to an event call silc_schedule_event_connect. + * To disconnect from event call silc_schedule_event_disconnect. + * To signal event call silc_schedule_event_signal. + * To delete event task call silc_schedule_task_del or + * silc_schedule_task_del_event. + * + * The variable argument list is used to describe the arguments of the + * event. The variable arguments are a list of zero or more SilcParam + * values. This function returns the event task context or NULL on error. + * + * EXAMPLE + * + * // Register 'connected' event + * silc_schedule_task_add_event(schedule, "connected", + * SILC_PARAM_UINT32, + * SILC_PARAM_BUFFER); + * + * // Connect to 'connected' event + * silc_schedule_event_connect(schedule, "connected", NULL, + * connected_cb, ctx); + * + * // Signal 'connected' event + * silc_schedule_event_signal(schedule, "connected", NULL, integer, buf); + * + * // 'connected' event handler + * SILC_TASK_CALLBACK(connected_cb) + * { + * FooCtx ctx = context; + * SilcUInt32 integer; + * SilcBuffer buf; + * + * integer = va_arg(va, SilcUInt32); + * buf = va_arg(va, SilcBuffer); + * ... + * } + * + ***/ +SilcTask silc_schedule_task_add_event(SilcSchedule schedule, + const char *event, ...); + /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del * * SYNOPSIS @@ -487,6 +701,9 @@ void silc_schedule_set_notify(SilcSchedule schedule, * in task callbacks (including in the task's own task callback) and * in multi-threaded environment in other threads as well. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task); @@ -506,6 +723,9 @@ SilcBool silc_schedule_task_del(SilcSchedule schedule, SilcTask task); * in task callbacks (including in the task's own task callback) and * in multi-threaded environment in other threads as well. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd); @@ -526,6 +746,9 @@ SilcBool silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd); * in task callbacks (including in the task's own task callback) and * in multi-threaded environment in other threads as well. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule, SilcTaskCallback callback); @@ -546,6 +769,9 @@ SilcBool silc_schedule_task_del_by_callback(SilcSchedule schedule, * in task callbacks (including in the task's own task callback) and * in multi-threaded environment in other threads as well. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule, void *context); @@ -567,11 +793,34 @@ SilcBool silc_schedule_task_del_by_context(SilcSchedule schedule, * in task callbacks (including in the task's own task callback) and * in multi-threaded environment in other threads as well. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd, SilcTaskCallback callback, void *context); +/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_event + * + * SYNOPSIS + * + * void silc_schedule_task_del_event(SilcSchedule schedule, + * const char *event); + * + * DESCRIPTION + * + * Deletes event task by the event name `event'. Returns FALSE if the + * event does not exist. Events can be deleted by calling the + * silc_schedule_task_del also. + * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * + ***/ +SilcBool silc_schedule_task_del_event(SilcSchedule schedule, + const char *event); + /****f* silcutil/SilcScheduleAPI/silc_schedule_set_listen_fd * * SYNOPSIS @@ -597,6 +846,9 @@ SilcBool silc_schedule_task_del_by_all(SilcSchedule schedule, int fd, * after the event occurs in reality. In normal cases the `send_events' * is set to FALSE. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * * Returns FALSE if the operation could not performed and TRUE if it * was a success. * @@ -616,6 +868,9 @@ SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd, * Returns the file descriptor `fd' current requested events mask, * or 0 on error. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule, SilcUInt32 fd); @@ -632,7 +887,101 @@ SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule, * file descriptor `fd'. No events will be detected for the `fd' * after calling this function. * + * If `schedule' is NULL this will call silc_schedule_get_global to try to + * get global scheduler. + * ***/ void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd); +/****f* silcutil/SilcScheduleAPI/silc_schedule_event_connect + * + * SYNOPSIS + * + * SilcBool silc_schedule_event_connect(SilcSchedule schedule, + * const char *event, SilcTask task, + * SilcTaskEventCallback callback, + * void *context); + * + * DESCRIPTION + * + * Connects to an event task. The `event' or `task' must be non-NULL. + * If `event' is non-NULL it is the name of the event to connect to. If + * the `task' is non-NULL it is the event task to connect to. The event + * SilcTask pointer is returned by silc_schedule_task_add_event when the + * even is added to scheduler. + * + * The `callback' with `context' and with `schedule' are called when the + * even task is signalled with silc_schedule_event_signal. + * + * Returns FALSE on error or if the `callback' with `context' has already + * been connected. Otherwise, returns TRUE. + * + * EXAMPLE + * + * silc_schedule_event_connect(schedule, "foo event", NULL, + * foo_signal_callback, foo_context); + * + ***/ +SilcBool silc_schedule_event_connect(SilcSchedule schedule, + const char *event, SilcTask task, + SilcTaskEventCallback callback, + void *context); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_event_disconnect + * + * SYNOPSIS + * + * SilcBool silc_schedule_event_disconnect(SilcSchedule schedule, + * const char *event, SilcTask task, + * SilcTaskEventCallback callback, + * void *context); + * + * DESCRIPTION + * + * Disconnects the `callback' and `context' from an event task. The `event' + * or `task' must be non-NULL. If `event' is non-NULL it is the name of + * the event. If `task' is non-NULL it is the event task. + * + * Returns FALSE on error or if the `callback' with `context' has not been + * connected. Otherwise, returns TRUE. + * + ***/ +SilcBool silc_schedule_event_disconnect(SilcSchedule schedule, + const char *event, SilcTask task, + SilcTaskEventCallback callback, + void *context); + +/****f* silcutil/SilcScheduleAPI/silc_schedule_event_signal + * + * SYNOPSIS + * + * SilcBool silc_schedule_event_signal(SilcSchedule schedule, + * const char *event, + * SilcTask task, ...); + * + * DESCRIPTION + * + * Signals an event task. The `event' or `task' must be non-NULL. If + * `event' is non-NULL it is the name of the event to signal. If the `task' + * is non-NULL it is the task to be signalled. It is marginally faster + * to use the `task' pointer directly instead of `event' to send the signal. + * + * The variable arguments are the arguments to be sent in the signal to + * the connected entities. The silc_schedule_task_add_event defines what + * arguments must be sent to each signal. + * + * Signal delivery is synchronous; the signal is delivered inside this + * function. If a receiver was originally in another thread, the signal + * is delivered in the thread where this function is called. This means + * that concurrency control (locking) is required if the application uses + * events in multiple threads. + * + * EXAMPLE + * + * silc_schedule_event_signal(schedule, "foo event", NULL, intarg, buffer); + * + ***/ +SilcBool silc_schedule_event_signal(SilcSchedule schedule, const char *event, + SilcTask task, ...); + #endif