include/isc/task.h

27 /*! \file isc/task.h
28  * \brief The task system provides a lightweight execution context, which is
31  * When a task's event queue is non-empty, the
32  * task is runnable.  A small work crew of threads, typically one per CPU,
56  * Events which have been queued for a task but not delivered may be removed
57  * from the task's event queue by purging or unsending.
109 /*% Task and task manager methods */
124 	void (*send)(isc_task_t *task, isc_event_t **eventp);
126 	unsigned int (*unsend)(isc_task_t *task, void *sender, isc_eventtype_t type,
128 	isc_result_t (*onshutdown)(isc_task_t *task, isc_taskaction_t action,
130 	void (*shutdown)(isc_task_t *task);
131 	void (*setname)(isc_task_t *task, const char *name, void *tag);
132 	unsigned int (*purgeevents)(isc_task_t *task, void *sender,
134 	unsigned int (*purgerange)(isc_task_t *task, void *sender,
137 	isc_result_t (*beginexclusive)(isc_task_t *task);
138 	void (*endexclusive)(isc_task_t *task);
139     void (*setprivilege)(isc_task_t *task, isc_boolean_t priv);
140     isc_boolean_t (*privilege)(isc_task_t *task);
144  * This structure is actually just the common prefix of a task manager
147  * Direct use of this structure by clients is forbidden.  task implementations
149  * of the isc_task_ routines to work.  task implementations must maintain
150  * all task invariants.
163  * This is the common prefix of a task object.  The same note as
180  * Create a task.
185  *	before the task must yield to other tasks waiting to execute.  If
186  *	quantum is zero, then the default quantum of the task manager will
195  *\li	'manager' is a valid task manager.
201  *\li	On success, '*taskp' is bound to the new task.
218  *\li	'source' is a valid task.
230  * Detach *taskp from its task.
234  *\li	'*taskp' is a valid task.
240  *\li	If '*taskp' is the last reference to the task, the task is idle (has
241  *	an empty event queue), and has not been shutdown, the task will be
244  *\li	If '*taskp' is the last reference to the task and
245  *	the task has been shutdown,
246  *		all resources used by the task will be freed.
250 isc_task_send(isc_task_t *task, isc_event_t **eventp);
252  * Send '*event' to 'task'.
256  *\li	'task' is a valid task.
268  * task.
272  *\li	'*taskp' is a valid task.
281  *\li	If '*taskp' is the last reference to the task, the task is
283  *	the task will be shutdown.
285  *\li	If '*taskp' is the last reference to the task and
286  *	the task has been shutdown,
287  *		all resources used by the task will be freed.
292 isc_task_purgerange(isc_task_t *task, void *sender, isc_eventtype_t first,
295  * Purge events from a task's event queue.
299  *\li	'task' is a valid task.
305  *\li	Events in the event queue of 'task' whose sender is 'sender', whose
318 isc_task_purge(isc_task_t *task, void *sender, isc_eventtype_t type,
321  * Purge events from a task's event queue.
328  *		isc_task_purgerange(task, sender, type, type, tag);
333  *\li	'task' is a valid task.
337  *\li	Events in the event queue of 'task' whose sender is 'sender', whose
350 isc_task_purgeevent(isc_task_t *task, isc_event_t *event);
352  * Purge 'event' from a task's event queue.
358  *\li	If 'event' is on the task's event queue, it will be purged,
360  *	on the task's event queue; in fact, it can even be an invalid
361  *	pointer.  Purging only occurs if the event is actually on the task's
364  * \li	Purging never changes the state of the task.
368  *\li	'task' is a valid task.
372  *\li	'event' is not in the event queue for 'task'.
382 isc_task_unsendrange(isc_task_t *task, void *sender, isc_eventtype_t first,
385  * Remove events from a task's event queue.
389  *\li	'task' is a valid task.
397  *\li	Events in the event queue of 'task' whose sender is 'sender', whose
410 isc_task_unsend(isc_task_t *task, void *sender, isc_eventtype_t type,
413  * Remove events from a task's event queue.
420  *		isc_task_unsendrange(task, sender, type, type, tag, events);
425  *\li	'task' is a valid task.
431  *\li	Events in the event queue of 'task' whose sender is 'sender', whose
441 isc_task_onshutdown(isc_task_t *task, isc_taskaction_t action,
445  * 'task' is shutdown.
453  *\li	'task' is a valid task.
455  *\li	'action' is a valid task action.
459  *\li	When the task is shutdown, shutdown events requested with
460  *	isc_task_onshutdown() will be appended to the task's event queue.
471 isc_task_shutdown(isc_task_t *task);
473  * Shutdown 'task'.
477  *\li	Shutting down a task causes any shutdown events requested with
478  *	isc_task_onshutdown() to be posted (in LIFO order).  The task
482  *\li	Trying to shutdown a task that has already been shutdown has no
487  *\li	'task' is a valid task.
511  *	'*taskp' is a valid task.
520  *\li	If '*taskp' is the last reference to the task,
521  *		all resources used by the task will be freed.
525 isc_task_setname(isc_task_t *task, const char *name, void *tag);
527  * Name 'task'.
533  *\li	Naming a task is currently only useful for debugging purposes.
537  *\li	'task' is a valid task.
541 isc_task_getname(isc_task_t *task);
543  * Get the name of 'task', as previously set using isc_task_setname().
549  *\li	'task' is a valid task.
553  * 	If the task has not been named, the string is
559 isc_task_gettag(isc_task_t *task);
561  * Get the tag value for  'task', as previously set using isc_task_settag().
567  *\li	'task' is a valid task.
571 isc_task_beginexclusive(isc_task_t *task);
573  * Request exclusive access for 'task', which must be the calling
574  * task.  Waits for any other concurrently executing tasks to finish their
576  * tasks sharing a task manager with 'task'.
582  *\li	'task' is the calling task.
585  *\li	#ISC_R_SUCCESS		The current task now has exclusive access.
586  *\li	#ISC_R_LOCKBUSY		Another task has already requested exclusive
591 isc_task_endexclusive(isc_task_t *task);
597  *\li	'task' is the calling task, and has obtained
602 isc_task_getcurrenttime(isc_task_t *task, isc_stdtime_t *t);
604  * Provide the most recent timestamp on the task.  The timestamp is considered
608  *\li	'task' is a valid task.
618  * Returns ISC_TRUE if the task is in the process of shutting down,
622  *\li	'task' is a valid task.
626 isc_task_setprivilege(isc_task_t *task, isc_boolean_t priv);
628  * Set or unset the task's "privileged" flag depending on the value of
631  * Under normal circumstances this flag has no effect on the task behavior,
632  * but when the task manager has been set to privileged exeuction mode via
635  * tasks have finished executing, the task manager will automatically
636  * return to normal execution mode and nonprivileged task can resume.
639  *\li	'task' is a valid task.
643 isc_task_privilege(isc_task_t *task);
645  * Returns the current value of the task's privilege flag.
648  *\li	'task' is a valid task.
663  * Create a new task manager.  isc_taskmgr_createinctx() also associates
690  *\li	On success, '*managerp' will be attached to the newly created task
699  *\li	#ISC_R_SHUTTINGDOWN      	The non-threaded, shared, task
709  * Set/get the current operating mode of the task manager.  Valid modes are:
718  * necessary to have at least one privileged task waiting on the ready
720  * which in turn means the task which calls this function should be in
721  * task-exclusive mode when it does so.
725  *\li      'manager' is a valid task manager.
739  *\li	isc_taskmgr_destroy() must not be called by a task event action,
741  *	complete.  An event action that wants to cause task manager shutdown
752  *\li	'*managerp' is a valid task manager.
758  *\li	All resources used by the task manager, and any tasks it managed,
780  * Register a new task management implementation and add it to the list of
788  * A short cut function that specifies the task management module in the ISC