X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_scheduler_lib.h;h=787fbd0139fba080ccc2206619ff74651005fd96;hb=cbd60b5e56aac2d6711e299086383f83357794f8;hp=4ee21e1930eea435f851fd72459b52505bf1118d;hpb=f1f603c7d0b3f03dca46a4f313472288eb080eb1;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_scheduler_lib.h b/src/include/gnunet_scheduler_lib.h index 4ee21e193..787fbd013 100644 --- a/src/include/gnunet_scheduler_lib.h +++ b/src/include/gnunet_scheduler_lib.h @@ -1,28 +1,29 @@ /* This file is part of GNUnet - (C) 2009-2013 Christian Grothoff (and other contributing authors) + Copyright (C) 2009-2016 GNUnet e.V. - GNUnet 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 3, or (at your - option) any later version. + GNUnet 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 3 of the License, + or (at your option) any later version. GNUnet 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. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Affero General Public License for more details. */ /** - * @file include/gnunet_scheduler_lib.h - * @brief API to schedule computations using continuation passing style * @author Christian Grothoff - * @defgroup scheduler Event loop (scheduler) + * + * @file + * API to schedule computations using continuation passing style + * + * @defgroup scheduler Scheduler library + * Event loop (scheduler) + * + * Schedule computations using continuation passing style. + * * @{ */ @@ -59,8 +60,7 @@ enum GNUNET_SCHEDULER_Reason GNUNET_SCHEDULER_REASON_STARTUP = 1, /** - * We are shutting down and are running all shutdown-related tasks - * (regardless of timeout, etc.). + * We are shutting down and are running all shutdown-related tasks. */ GNUNET_SCHEDULER_REASON_SHUTDOWN = 2, @@ -87,75 +87,86 @@ enum GNUNET_SCHEDULER_Reason }; +#include "gnunet_time_lib.h" +#include "gnunet_network_lib.h" + + /** - * Valid task priorities. Use these, do not - * pass random integers! + * Possible events on FDs, used as a bitmask. + * Modelled after GPollFD. */ -enum GNUNET_SCHEDULER_Priority +enum GNUNET_SCHEDULER_EventType { + /** - * Run with the same priority as the current job. + * No event (useful for timeout). */ - GNUNET_SCHEDULER_PRIORITY_KEEP = 0, + GNUNET_SCHEDULER_ET_NONE = 0, /** - * Run when otherwise idle. + * Data available for reading. */ - GNUNET_SCHEDULER_PRIORITY_IDLE = 1, + GNUNET_SCHEDULER_ET_IN = 1, /** - * Run as background job (higher than idle, - * lower than default). + * Buffer available for writing. */ - GNUNET_SCHEDULER_PRIORITY_BACKGROUND = 2, + GNUNET_SCHEDULER_ET_OUT = 2, /** - * Run with the default priority (normal - * P2P operations). Any task that is scheduled - * without an explicit priority being specified - * will run with this priority. + * */ - GNUNET_SCHEDULER_PRIORITY_DEFAULT = 3, + GNUNET_SCHEDULER_ET_HUP = 4, /** - * Run with high priority (important requests). - * Higher than DEFAULT. + * */ - GNUNET_SCHEDULER_PRIORITY_HIGH = 4, + GNUNET_SCHEDULER_ET_ERR = 8, /** - * Run with priority for interactive tasks. - * Higher than "HIGH". + * */ - GNUNET_SCHEDULER_PRIORITY_UI = 5, + GNUNET_SCHEDULER_ET_PRI = 16, /** - * Run with priority for urgent tasks. Use - * for things like aborts and shutdowns that - * need to preempt "UI"-level tasks. - * Higher than "UI". + * */ - GNUNET_SCHEDULER_PRIORITY_URGENT = 6, + GNUNET_SCHEDULER_ET_NVAL = 32 + +}; + + +/** + * Information about an event relating to a file descriptor/socket. + */ +struct GNUNET_SCHEDULER_FdInfo +{ /** - * This is an internal priority level that is only used for tasks - * that are being triggered due to shutdown (they have automatically - * highest priority). User code must not use this priority level - * directly. Tasks run with this priority level that internally - * schedule other tasks will see their original priority level - * be inherited (unless otherwise specified). + * GNUnet network socket the event is about, matches @a sock, + * NULL if this is about a file handle or if no network + * handle was given to the scheduler originally. */ - GNUNET_SCHEDULER_PRIORITY_SHUTDOWN = 7, + const struct GNUNET_NETWORK_Handle *fd; /** - * Number of priorities (must be the last priority). - * This priority must not be used by clients. + * GNUnet file handle the event is about, matches @a sock, + * NULL if this is about a network socket or if no network + * handle was given to the scheduler originally. */ - GNUNET_SCHEDULER_PRIORITY_COUNT = 8 -}; + const struct GNUNET_DISK_FileHandle *fh; -#include "gnunet_time_lib.h" -#include "gnunet_network_lib.h" + /** + * Type of the event that was generated related to @e sock. + */ + enum GNUNET_SCHEDULER_EventType et; + + /** + * Underlying OS handle the event was about. + */ + int sock; + +}; /** @@ -169,31 +180,207 @@ struct GNUNET_SCHEDULER_TaskContext enum GNUNET_SCHEDULER_Reason reason; /** - * Set of file descriptors ready for reading; - * note that additional bits may be set - * that were not in the original request + * Length of the following array. + */ + unsigned int fds_len; + + /** + * Array of length @e fds_len with information about ready FDs. + * Note that we use the same format regardless of the internal + * event loop that was used. The given array should only contain + * information about file descriptors relevant to the current task. + */ + const struct GNUNET_SCHEDULER_FdInfo *fds; + + /** + * Set of file descriptors ready for reading; note that additional + * bits may be set that were not in the original request. + * @deprecated */ const struct GNUNET_NETWORK_FDSet *read_ready; /** - * Set of file descriptors ready for writing; - * note that additional bits may be set - * that were not in the original request. + * Set of file descriptors ready for writing; note that additional + * bits may be set that were not in the original request. + * @deprecated */ const struct GNUNET_NETWORK_FDSet *write_ready; }; +/** + * Function used by event-loop implementations to signal the scheduler + * that a particular @a task is ready due to an event specified in the + * et field of @a fdi. + * + * This function will then queue the task to notify the application + * that the task is ready (with the respective priority). + * + * @param task the task that is ready + * @param fdi information about the related FD + */ +void +GNUNET_SCHEDULER_task_ready (struct GNUNET_SCHEDULER_Task *task, + struct GNUNET_SCHEDULER_FdInfo *fdi); + + +/** + * Handle to the scheduler's state to be used by the driver. + */ +struct GNUNET_SCHEDULER_Handle; + + +/** + * Function called by external event loop implementations to tell the + * scheduler to run some of the tasks that are ready. Must be called + * only after #GNUNET_SCHEDULER_driver_init has been called and before + * #GNUNET_SCHEDULER_driver_done is called. + * This function may return even though there are tasks left to run + * just to give other tasks a chance as well. If we return #GNUNET_YES, + * the event loop implementation should call this function again as + * soon as possible, while if we return #GNUNET_NO it must block until + * either the operating system has more work (the scheduler has no more + * work to do right now) or the timeout set by the scheduler (using the + * set_wakeup callback) is reached. + * + * @param sh scheduler handle that was returned by + * #GNUNET_SCHEDULER_driver_init + * @return #GNUNET_YES if there are more tasks that are ready, + * and thus we would like to run more (yield to avoid + * blocking other activities for too long) #GNUNET_NO + * if we are done running tasks (yield to block) + */ +int +GNUNET_SCHEDULER_do_work (struct GNUNET_SCHEDULER_Handle *sh); + + +/** + * API an external event loop has to implement for + * #GNUNET_SCHEDULER_driver_init. + */ +struct GNUNET_SCHEDULER_Driver +{ + + /** + * Closure to pass to the functions in this struct. + */ + void *cls; + + /** + * Add a @a task to be run if the conditions specified in the + * et field of the given @a fdi are satisfied. The et field will + * be cleared after this call and the driver is expected to set + * the type of the actual event before passing @a fdi to + * #GNUNET_SCHEDULER_task_ready. + * + * @param cls closure + * @param task task to add + * @param fdi conditions to watch for + * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure + * (i.e. @a fdi too high or invalid) + */ + int + (*add)(void *cls, + struct GNUNET_SCHEDULER_Task *task, + struct GNUNET_SCHEDULER_FdInfo *fdi); + + /** + * Delete a @a task from the set of tasks to be run. A task may + * comprise multiple FdInfo entries previously added with the add + * function. The driver is expected to delete them all. + * + * @param cls closure + * @param task task to delete + * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure + * (i.e. @a task does not match prior @e add call) + */ + int + (*del)(void *cls, + struct GNUNET_SCHEDULER_Task *task); + + /** + * Set time at which we definitively want to get a wakeup call. + * + * @param cls closure + * @param dt time when we want to wake up next + */ + void + (*set_wakeup)(void *cls, + struct GNUNET_TIME_Absolute dt); + +}; + + /** * Signature of the main function of a task. * * @param cls closure - * @param tc context information (why was this task triggered now) */ typedef void -(*GNUNET_SCHEDULER_TaskCallback) (void *cls, - const struct GNUNET_SCHEDULER_TaskContext *tc); +(*GNUNET_SCHEDULER_TaskCallback) (void *cls); + + +/** + * Function called by external event loop implementations to initialize + * the scheduler. An external implementation has to provide @a driver + * which contains callbacks for the scheduler (see definition of struct + * #GNUNET_SCHEDULER_Driver). The callbacks are used to instruct the + * external implementation to watch for events. If it detects any of + * those events it is expected to call #GNUNET_SCHEDULER_do_work to let + * the scheduler handle it. If an event is related to a specific task + * (e.g. the scheduler gave instructions to watch a file descriptor), + * the external implementation is expected to mark that task ready + * before by calling #GNUNET_SCHEDULER_task_ready. + * + * This function has to be called before any tasks are scheduled and + * before GNUNET_SCHEDULER_do_work is called for the first time. It + * allocates resources that have to be freed again by calling + * #GNUNET_SCHEDULER_driver_done. + * + * This function installs the same signal handlers as + * #GNUNET_SCHEDULER_run. This means SIGTERM (and other similar signals) + * will induce a call to #GNUNET_SCHEDULER_shutdown during the next + * call to #GNUNET_SCHEDULER_do_work. As a result, SIGTERM causes all + * active tasks to be scheduled with reason + * #GNUNET_SCHEDULER_REASON_SHUTDOWN. (However, tasks added afterwards + * will execute normally!). Note that any particular signal will only + * shut down one scheduler; applications should always only create a + * single scheduler. + * + * @param driver to use for the event loop + * @return handle to be passed to #GNUNET_SCHEDULER_do_work and + * #GNUNET_SCHEDULER_driver_done + */ +struct GNUNET_SCHEDULER_Handle * +GNUNET_SCHEDULER_driver_init (const struct GNUNET_SCHEDULER_Driver *driver); + + +/** + * Counter-part of #GNUNET_SCHEDULER_driver_init. Has to be called + * by external event loop implementations after the scheduler has + * shut down. This is the case if both of the following conditions + * are met: + * + * - all tasks the scheduler has added through the driver's add + * callback have been removed again through the driver's del + * callback + * - the timeout the scheduler has set through the driver's + * add_wakeup callback is FOREVER + * + * @param sh the handle returned by #GNUNET_SCHEDULER_driver_init + */ +void +GNUNET_SCHEDULER_driver_done (struct GNUNET_SCHEDULER_Handle *sh); + + +/** + * Obtain the driver for using select() as the event loop. + * + * @return NULL on error + */ +struct GNUNET_SCHEDULER_Driver * +GNUNET_SCHEDULER_driver_select (void); /** @@ -220,26 +407,41 @@ typedef int * tasks have completed. On systems with signals, receiving a SIGTERM * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown * to be run after the active task is complete. As a result, SIGTERM - * causes all active tasks to be scheduled with reason + * causes all shutdown tasks to be scheduled with reason * #GNUNET_SCHEDULER_REASON_SHUTDOWN. (However, tasks added * afterwards will execute normally!). Note that any particular * signal will only shut down one scheduler; applications should * always only create a single scheduler. * * @param task task to run first (and immediately) - * @param task_cls closure of task + * @param task_cls closure of @a task */ void GNUNET_SCHEDULER_run (GNUNET_SCHEDULER_TaskCallback task, void *task_cls); +/** + * Initialize and run scheduler. This function will return when all + * tasks have completed. When @ install_signals is GNUNET_YES, then + * this function behaves in the same was as GNUNET_SCHEDULER_run does. + * If @ install_signals is GNUNET_NO then no signal handlers are + * installed. + * + * @param install_signals whether to install signals (GNUNET_YES/NO) + * @param task task to run first (and immediately) + * @param task_cls closure of @a task + */ +void +GNUNET_SCHEDULER_run_with_optional_signals (int install_signals, + GNUNET_SCHEDULER_TaskCallback task, + void *task_cls); + /** - * Request the shutdown of the scheduler. Marks all currently - * pending tasks as ready because of shutdown. This will - * cause all tasks to run (as soon as possible, respecting - * priorities and prerequisite tasks). Note that tasks - * scheduled AFTER this call may still be delayed arbitrarily. + * Request the shutdown of a scheduler. Marks all tasks + * awaiting shutdown as ready. Note that tasks + * scheduled with #GNUNET_SCHEDULER_add_shutdown() AFTER this call + * will be delayed until the next shutdown signal. */ void GNUNET_SCHEDULER_shutdown (void); @@ -261,42 +463,31 @@ GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p); /** - * Obtain the reason code for why the current task was - * started. Will return the same value as - * the GNUNET_SCHEDULER_TaskContext's reason field. + * Obtain the reasoning why the current task was + * started. * - * @return reason(s) why the current task is run + * @return task context with information why the current task is run */ -enum GNUNET_SCHEDULER_Reason -GNUNET_SCHEDULER_get_reason (void); +const struct GNUNET_SCHEDULER_TaskContext * +GNUNET_SCHEDULER_get_task_context (void); /** * Cancel the task with the specified identifier. - * The task must not yet have run. + * The task must not yet have run. Only allowed to be called as long as the + * scheduler is running, that is one of the following conditions is met: + * + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet * * @param task id of the task to cancel - * @return the closure of the callback of the cancelled task + * @return original closure of the task */ void * GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task); -/** - * Continue the current execution with the given function. This is - * similar to the other "add" functions except that there is no delay - * and the reason code can be specified. - * - * @param task main function of the task - * @param task_cls closure of task - * @param reason reason for task invocation - */ -void -GNUNET_SCHEDULER_add_continuation (GNUNET_SCHEDULER_TaskCallback task, - void *task_cls, - enum GNUNET_SCHEDULER_Reason reason); - - /** * Continue the current execution with the given function. This is * similar to the other "add" functions except that there is no delay @@ -308,10 +499,10 @@ GNUNET_SCHEDULER_add_continuation (GNUNET_SCHEDULER_TaskCallback task, * @param priority priority to use for the task */ void -GNUNET_SCHEDULER_add_continuation_with_priority (GNUNET_SCHEDULER_TaskCallback task, - void *task_cls, - enum GNUNET_SCHEDULER_Reason reason, - enum GNUNET_SCHEDULER_Priority priority); +GNUNET_SCHEDULER_add_with_reason_and_priority (GNUNET_SCHEDULER_TaskCallback task, + void *task_cls, + enum GNUNET_SCHEDULER_Reason reason, + enum GNUNET_SCHEDULER_Priority priority); /** @@ -349,6 +540,21 @@ GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_TaskCallback task, void *task_cls); +/** + * Schedule a new task to be run on shutdown, that is when a CTRL-C + * signal is received, or when #GNUNET_SCHEDULER_shutdown() is being + * invoked. + * + * @param task main function of the task + * @param task_cls closure of @a task + * @return unique task identifier for the job + * only valid until @a task is started! + */ +struct GNUNET_SCHEDULER_Task * +GNUNET_SCHEDULER_add_shutdown (GNUNET_SCHEDULER_TaskCallback task, + void *task_cls); + + /** * Schedule a new task to be run as soon as possible with the * (transitive) ignore-shutdown flag either explicitly set or @@ -374,8 +580,7 @@ GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness, * will be scheduled for execution once the delay has expired. It * will be run with the DEFAULT priority. * - * * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * @param delay with which the operation should be run * @param task main function of the task * @param task_cls closure of @a task * @return unique task identifier for the job @@ -387,12 +592,28 @@ GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay, void *task_cls); +/** + * Schedule a new task to be run at the specified time. The task + * will be scheduled for execution once specified time has been + * reached. It will be run with the DEFAULT priority. + * + * @param at time at which this operation should run + * @param task main function of the task + * @param task_cls closure of @a task + * @return unique task identifier for the job + * only valid until @a task is started! + */ +struct GNUNET_SCHEDULER_Task * +GNUNET_SCHEDULER_add_at (struct GNUNET_TIME_Absolute at, + GNUNET_SCHEDULER_TaskCallback task, + void *task_cls); + + /** * Schedule a new task to be run with a specified delay. The task * will be scheduled for execution once the delay has expired. * - * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * @param delay when should this operation time out? * @param priority priority to use for the task * @param task main function of the task * @param task_cls closure of @a task @@ -406,15 +627,38 @@ GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay, void *task_cls); +/** + * Schedule a new task to be run at the specified time. The task + * will be scheduled for execution at time @a at. + * + * @param at time when the operation should run + * @param priority priority to use for the task + * @param task main function of the task + * @param task_cls closure of @a task + * @return unique task identifier for the job + * only valid until @a task is started! + */ +struct GNUNET_SCHEDULER_Task * +GNUNET_SCHEDULER_add_at_with_priority (struct GNUNET_TIME_Absolute at, + enum GNUNET_SCHEDULER_Priority priority, + GNUNET_SCHEDULER_TaskCallback task, + void *task_cls); + + /** * Schedule a new task to be run with a specified delay or when the * specified file descriptor is ready for reading. The delay can be * used as a timeout on the socket being ready. The task will be * scheduled for execution once either the delay has expired or the * socket operation is ready. It will be run with the DEFAULT priority. + * Only allowed to be called as long as the scheduler is running, that + * is one of the following conditions is met: * - * * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet + * + * @param delay when should this operation time out? * @param rfd read file-descriptor * @param task main function of the task * @param task_cls closure of @a task @@ -435,9 +679,14 @@ GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay, * socket being ready. The task will be scheduled for execution once * either the delay has expired or the socket operation is ready. It * will be run with the DEFAULT priority. + * Only allowed to be called as long as the scheduler is running, that + * is one of the following conditions is met: + * + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet * - * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * @param delay when should this operation time out? * @param priority priority to use for the task * @param rfd read file-descriptor * @param task main function of the task @@ -458,10 +707,16 @@ GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay, * specified file descriptor is ready for writing. The delay can be * used as a timeout on the socket being ready. The task will be * scheduled for execution once either the delay has expired or the - * socket operation is ready. It will be run with the DEFAULT priority. + * socket operation is ready. It will be run with the priority of + * the calling task. + * Only allowed to be called as long as the scheduler is running, that + * is one of the following conditions is met: * - * * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet + * + * @param delay when should this operation time out? * @param wfd write file-descriptor * @param task main function of the task * @param task_cls closure of @a task @@ -481,15 +736,20 @@ GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay, * used as a timeout on the socket being ready. The task will be * scheduled for execution once either the delay has expired or the * socket operation is ready. + * Only allowed to be called as long as the scheduler is running, that + * is one of the following conditions is met: + * + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet * - * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * @param delay when should this operation time out? * @param priority priority of the task * @param fd file-descriptor * @param on_read whether to poll the file-descriptor for readability * @param on_write whether to poll the file-descriptor for writability * @param task main function of the task - * @param task_cls closure of @a task + * @param task_cls closure of task * @return unique task identifier for the job * only valid until "task" is started! */ @@ -502,20 +762,26 @@ GNUNET_SCHEDULER_add_net_with_priority (struct GNUNET_TIME_Relative delay, GNUNET_SCHEDULER_TaskCallback task, void *task_cls); + /** * Schedule a new task to be run with a specified delay or when the * specified file descriptor is ready for reading. The delay can be * used as a timeout on the socket being ready. The task will be * scheduled for execution once either the delay has expired or the * socket operation is ready. It will be run with the DEFAULT priority. + * Only allowed to be called as long as the scheduler is running, that + * is one of the following conditions is met: * - * * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet + * + * @param delay when should this operation time out? * @param rfd read file-descriptor * @param task main function of the task * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ struct GNUNET_SCHEDULER_Task * GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay, @@ -530,9 +796,14 @@ GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay, * used as a timeout on the socket being ready. The task will be * scheduled for execution once either the delay has expired or the * socket operation is ready. It will be run with the DEFAULT priority. + * Only allowed to be called as long as the scheduler is running, that + * is one of the following conditions is met: + * + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet * - * * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * @param delay when should this operation time out? * @param wfd write file-descriptor * @param task main function of the task * @param task_cls closure of @a task @@ -552,9 +823,14 @@ GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay, * used as a timeout on the socket being ready. The task will be * scheduled for execution once either the delay has expired or the * socket operation is ready. + * Only allowed to be called as long as the scheduler is running, that + * is one of the following conditions is met: + * + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet * - * @param delay when should this operation time out? Use - * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * @param delay when should this operation time out? * @param priority priority of the task * @param fd file-descriptor * @param on_read whether to poll the file-descriptor for readability @@ -586,19 +862,23 @@ GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay, * (prerequisite-run) * && (delay-ready * || any-rs-ready - * || any-ws-ready - * || shutdown-active) + * || any-ws-ready) ) * + * Only allowed to be called as long as the scheduler is running, that + * is one of the following conditions is met: + * + * - #GNUNET_SCHEDULER_run has been called and has not returned yet + * - #GNUNET_SCHEDULER_driver_init has been run and + * #GNUNET_SCHEDULER_driver_done has not been called yet * * @param prio how important is this task? - * @param delay how long should we wait? Use #GNUNET_TIME_UNIT_FOREVER_REL for "forever", - * which means that the task will only be run after we receive SIGTERM + * @param delay how long should we wait? * @param rs set of file descriptors we want to read (can be NULL) * @param ws set of file descriptors we want to write (can be NULL) * @param task main function of the task * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ struct GNUNET_SCHEDULER_Task * GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio, @@ -612,15 +892,13 @@ GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio, * Sets the select function to use in the scheduler (scheduler_select). * * @param new_select new select function to use (NULL to reset to default) - * @param new_select_cls closure for 'new_select' + * @param new_select_cls closure for @a new_select */ void GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select, void *new_select_cls); -/** @} */ /* end of group scheduler */ - #if 0 /* keep Emacsens' auto-indent happy */ { #endif @@ -629,3 +907,5 @@ GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select, #endif #endif + +/** @} */ /* end of group scheduler */