-/****h* silcutil/silcschedule.h
- *
- * NAME
- *
- * silcschedule.h
- *
- * COPYRIGHT
- *
- * Author: Pekka Riikonen <priikone@silcnet.org>
- *
- * Copyright (C) 1998 - 2001 Pekka Riikonen
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+/*
+
+ silcschedule.h
+
+ COPYRIGHT
+
+ Author: Pekka Riikonen <priikone@silcnet.org>
+
+ Copyright (C) 1998 - 2001 Pekka Riikonen
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+*/
+
+/****h* silcutil/SilcScheduleAPI
*
- # DESCRIPTION
+ * DESCRIPTION
*
* The SILC Scheduler is the heart of any application. The scheduler provides
* the application's main loop that can handle incoming data, outgoing data,
* the scheduler's run function returns the application is considered to be
* ended.
*
- * On WIN32 systems the SILC Scheduler is also designed to work as the main
+ * On WIN32 systems the SILC Scheduler is too designed to work as the main
* loop of the GUI application. It can handle all Windows messages and
- * it dispatches them from the scheduler and thus makes it possible to
+ * it dispatches them from the scheduler, and thus makes it possible to
* create GUI applications. The scheduler can also handle all kinds of
* WIN32 handles, this includes sockets created by the SILC Net API routines,
- * WSAEVENT handle objects and arbitrary WIN32 HANDLE objects.
+ * WSAEVENT handle objects created by Winsock2 routines and arbitrary
+ * WIN32 HANDLE objects.
*
* The SILC Scheduler supports multi-threads as well. The actual scheduler
* must be run in single-thread but other threads may register new tasks
* application could be created by allocating own scheduler for each of the
* worker threads.
*
- */
+ ***/
#ifndef SILCSCHEDULE_H
#define SILCSCHEDULE_H
for example, receiving packets from network and sending packets to
network. It doesn't make much sense to register a task that receives
a packet from network to every connection when you can have one task
- that applies to all connections. This is what generic tasks are for-
+ that applies to all connections. This is what generic tasks are for.
Generic tasks are not bound to any specific file descriptor, however,
the correct file descriptor must be passed as argument to task
registering function. */
* event of the task. This type will be given as argument to the
* SilcTaskCallback function to indicate the event for the caller.
* The SILC_TASK_READ and SILC_TASK_WRITE may be set by the caller
- * of the silc_schedule_set_listen_fd if the caller needs to control
- * the events for the task. The SILC_TASK_TIMEOUT is set always only
- * by the scheduler when timeout for timeout task occurs.
+ * of the silc_schedule_set_listen_fd, if the caller needs to control
+ * the events for the task. The SILC_TASK_EXPIRE is set always only
+ * by the scheduler when timeout expires for timeout task.
*
* SOURCE
*/
*
* NAME
*
- * typedef enum { ... } SilcTaskPriority
+ * typedef enum { ... } SilcTaskPriority;
*
* DESCRIPTION
*
same way. Life is not fair for tasks with this priority. */
SILC_TASK_PRI_LOW,
- /* Normal priority that is used mostly in Silc. This is priority that
+ /* Normal priority that is used mostly in SILC. This is priority that
should always be used unless you specificly need some other priority.
The scheduler will run this task as soon as its timeout has expired.
For non-timeout tasks this priority behaves same way. Tasks are run
} SilcTaskPriority;
/***/
-/****f* silcutil/SilcScheduleAPI/silc_schedule_init
+/****f* silcutil/SilcScheduleAPI/SilcTaskCallback
*
* SYNOPSIS
*
* typedef void (*SilcTaskCallback)(SilcSchedule schedule,
- * SilcTaskEvent type, uint32 fd,
+ * SilcTaskEvent type, SilcUInt32 fd,
* void *context);
*
* DESCRIPTION
* The `schedule' is the scheduler context, the `type' is the indicated
* event, the `fd' is the file descriptor of the task and the `context'
* is a caller specified context. If multiple events occurred this
- * call is called separately for all events.
+ * callback is called separately for all events.
*
* To specify task callback function in the application using the
* SILC_TASK_CALLBACK and SILC_TASK_CALLBACK_GLOBAL macros is
*
***/
typedef void (*SilcTaskCallback)(SilcSchedule schedule, SilcTaskEvent type,
- uint32 fd, void *context);
+ SilcUInt32 fd, void *context);
/* Macros */
*/
#define SILC_TASK_CALLBACK(func) \
static void func(SilcSchedule schedule, SilcTaskEvent type, \
- uint32 fd, void *context)
+ SilcUInt32 fd, void *context)
/***/
-/****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK
+/****d* silcutil/SilcScheduleAPI/SILC_TASK_CALLBACK_GLOBAL
*
* NAME
*
* Generic macro to define task callback functions. This defines a
* function with name `func' as a task callback function. This
* differs from SILC_TASK_CALLBACK in that the defined function is
- * not static function.
+ * not static.
*
* SOURCE
*/
#define SILC_TASK_CALLBACK_GLOBAL(func) \
void func(SilcSchedule schedule, SilcTaskEvent type, \
- uint32 fd, void *context)
+ SilcUInt32 fd, void *context)
/***/
/* Prototypes */
* DESCRIPTION
*
* Initializes the scheduler. This returns the scheduler context that
- * is given as arugment usually to all silc_schedule_* functions.
+ * is given as argument usually to all silc_schedule_* functions.
* The `max_tasks' indicates the number of maximum tasks that the
* scheduler can handle.
*
*
* DESCRIPTION
*
- * Uninitializes the schedule. This is called when the program is ready
+ * Uninitializes the scheduler. This is called when the program is ready
* to end. This removes all tasks from the scheduler. Returns FALSE if the
* scheduler could not be uninitialized. This happens when the scheduler
* is still valid and silc_schedule_stop has not been called.
***/
bool silc_schedule_uninit(SilcSchedule schedule);
+/****f* silcutil/SilcScheduleAPI/silc_schedule_reinit
+ *
+ * SYNOPSIS
+ *
+ * SilcSchedule silc_schedule_reinit(int max_tasks);
+ *
+ * DESCRIPTION
+ *
+ * This function can be called to enlarge the task handling capabilities
+ * of the scheduler indicated by `schedule'. The `max_tasks' must be
+ * larger than what was set in silc_schedule_init function. This function
+ * returns FALSE if it cannot reinit the scheduler. This function does
+ * not do anything else except ready the scheduler to handle `max_tasks'
+ * number of tasks after this function returns. It is safe to call this
+ * function at any time, and it is guaranteed that existing tasks remain
+ * as they are in the scheduler.
+ *
+ ***/
+bool silc_schedule_reinit(SilcSchedule schedule, int max_tasks);
+
/****f* silcutil/SilcScheduleAPI/silc_schedule_stop
*
* SYNOPSIS
*
* Stops the scheduler even if it is not supposed to be stopped yet.
* After calling this, one must call silc_schedule_uninit (after the
- * silc_schedule has returned).
+ * silc_schedule has returned). After this is called it is guaranteed
+ * that next time the scheduler enters the main loop it will be stopped.
+ * However, untill it enters the main loop it will not detect that
+ * it is stopped for example if this is called from another thread.
*
***/
void silc_schedule_stop(SilcSchedule schedule);
***/
void silc_schedule(SilcSchedule schedule);
-/****f* silcutil/SilcScheduleAPI/silc_schedule
+/****f* silcutil/SilcScheduleAPI/silc_schedule_one
*
* SYNOPSIS
*
*
* SYNOPSIS
*
- * SilcTask silc_schedule_task_add(SilcSchedule schedule, uint32 fd,
+ * SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
* SilcTaskCallback callback,
* void *context,
* long seconds, long useconds,
* should also pass 0 as timeout, as the timeout will be ignored anyway.
* Also, note, that one cannot register timeout task with 0 timeout.
* There cannot be zero timeouts, passing zero means no timeout is used
- * for the task and SILC_TASK_FD_TASK is used as default task type in
+ * for the task and SILC_TASK_FD is used as default task type in
* this case.
*
* The `schedule' is the scheduler context. The `fd' is the file
* in other threads as well.
*
***/
-SilcTask silc_schedule_task_add(SilcSchedule schedule, uint32 fd,
+SilcTask silc_schedule_task_add(SilcSchedule schedule, SilcUInt32 fd,
SilcTaskCallback callback, void *context,
long seconds, long useconds,
SilcTaskType type,
*
* SYNOPSIS
*
- * void silc_schedule_task_del_by_fd(SilcSchedule schedule, uint32 fd);
+ * void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
*
* DESCRIPTION
*
* in task callbacks (including in the task's own task callback) and
* in multi-threaded environment in other threads as well.
*
+ * Note that generic tasks cannot be deleted using this function
+ * since generic tasks does not match any specific fd.
+ *
***/
-void silc_schedule_task_del_by_fd(SilcSchedule schedule, uint32 fd);
+void silc_schedule_task_del_by_fd(SilcSchedule schedule, SilcUInt32 fd);
/****f* silcutil/SilcScheduleAPI/silc_schedule_task_del_by_callback
*
*
* SYNOPSIS
*
- * void silc_schedule_set_listen_fd(SilcSchedule schedule, uint32 fd,
+ * void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
* SilcTaskEvent mask);
*
* DESCRIPTION
* times to change the events.
*
***/
-void silc_schedule_set_listen_fd(SilcSchedule schedule, uint32 fd,
+void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
SilcTaskEvent mask);
/****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
*
* SYNOPSIS
*
- * void silc_schedule_unset_listen_fd(SilcSchedule schedule, uint32 fd);
+ * void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
*
* DESCRIPTION
*
* after calling this function.
*
***/
-void silc_schedule_unset_listen_fd(SilcSchedule schedule, uint32 fd);
+void silc_schedule_unset_listen_fd(SilcSchedule schedule, SilcUInt32 fd);
#endif
projects / silc.git / blobdiff