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 */
118 	void (*setexcltask)(isc_taskmgr_t *mgr, isc_task_t *task);
126 	void (*send)(isc_task_t *task, isc_event_t **eventp);
128 	unsigned int (*unsend)(isc_task_t *task, void *sender, isc_eventtype_t type,
130 	isc_result_t (*onshutdown)(isc_task_t *task, isc_taskaction_t action,
132 	void (*shutdown)(isc_task_t *task);
133 	void (*setname)(isc_task_t *task, const char *name, void *tag);
134 	unsigned int (*purgeevents)(isc_task_t *task, void *sender,
136 	unsigned int (*purgerange)(isc_task_t *task, void *sender,
139 	isc_result_t (*beginexclusive)(isc_task_t *task);
140 	void (*endexclusive)(isc_task_t *task);
141     void (*setprivilege)(isc_task_t *task, isc_boolean_t priv);
142     isc_boolean_t (*privilege)(isc_task_t *task);
146  * This structure is actually just the common prefix of a task manager
149  * Direct use of this structure by clients is forbidden.  task implementations
151  * of the isc_task_ routines to work.  task implementations must maintain
152  * all task invariants.
165  * This is the common prefix of a task object.  The same note as
182  * Create a task.
187  *	before the task must yield to other tasks waiting to execute.  If
188  *	quantum is zero, then the default quantum of the task manager will
197  *\li	'manager' is a valid task manager.
203  *\li	On success, '*taskp' is bound to the new task.
220  *\li	'source' is a valid task.
232  * Detach *taskp from its task.
236  *\li	'*taskp' is a valid task.
242  *\li	If '*taskp' is the last reference to the task, the task is idle (has
243  *	an empty event queue), and has not been shutdown, the task will be
246  *\li	If '*taskp' is the last reference to the task and
247  *	the task has been shutdown,
248  *		all resources used by the task will be freed.
252 isc_task_send(isc_task_t *task, isc_event_t **eventp);
254  * Send '*event' to 'task'.
258  *\li	'task' is a valid task.
270  * task.
274  *\li	'*taskp' is a valid task.
283  *\li	If '*taskp' is the last reference to the task, the task is
285  *	the task will be shutdown.
287  *\li	If '*taskp' is the last reference to the task and
288  *	the task has been shutdown,
289  *		all resources used by the task will be freed.
294 isc_task_purgerange(isc_task_t *task, void *sender, isc_eventtype_t first,
297  * Purge events from a task's event queue.
301  *\li	'task' is a valid task.
307  *\li	Events in the event queue of 'task' whose sender is 'sender', whose
320 isc_task_purge(isc_task_t *task, void *sender, isc_eventtype_t type,
323  * Purge events from a task's event queue.
330  *		isc_task_purgerange(task, sender, type, type, tag);
335  *\li	'task' is a valid task.
339  *\li	Events in the event queue of 'task' whose sender is 'sender', whose
352 isc_task_purgeevent(isc_task_t *task, isc_event_t *event);
354  * Purge 'event' from a task's event queue.
360  *\li	If 'event' is on the task's event queue, it will be purged,
362  *	on the task's event queue; in fact, it can even be an invalid
363  *	pointer.  Purging only occurs if the event is actually on the task's
366  * \li	Purging never changes the state of the task.
370  *\li	'task' is a valid task.
374  *\li	'event' is not in the event queue for 'task'.
384 isc_task_unsendrange(isc_task_t *task, void *sender, isc_eventtype_t first,
387  * Remove events from a task's event queue.
391  *\li	'task' is a valid task.
399  *\li	Events in the event queue of 'task' whose sender is 'sender', whose
412 isc_task_unsend(isc_task_t *task, void *sender, isc_eventtype_t type,
415  * Remove events from a task's event queue.
422  *		isc_task_unsendrange(task, sender, type, type, tag, events);
427  *\li	'task' is a valid task.
433  *\li	Events in the event queue of 'task' whose sender is 'sender', whose
443 isc_task_onshutdown(isc_task_t *task, isc_taskaction_t action,
447  * 'task' is shutdown.
455  *\li	'task' is a valid task.
457  *\li	'action' is a valid task action.
461  *\li	When the task is shutdown, shutdown events requested with
462  *	isc_task_onshutdown() will be appended to the task's event queue.
473 isc_task_shutdown(isc_task_t *task);
475  * Shutdown 'task'.
479  *\li	Shutting down a task causes any shutdown events requested with
480  *	isc_task_onshutdown() to be posted (in LIFO order).  The task
484  *\li	Trying to shutdown a task that has already been shutdown has no
489  *\li	'task' is a valid task.
513  *	'*taskp' is a valid task.
522  *\li	If '*taskp' is the last reference to the task,
523  *		all resources used by the task will be freed.
527 isc_task_setname(isc_task_t *task, const char *name, void *tag);
529  * Name 'task'.
535  *\li	Naming a task is currently only useful for debugging purposes.
539  *\li	'task' is a valid task.
543 isc_task_getname(isc_task_t *task);
545  * Get the name of 'task', as previously set using isc_task_setname().
551  *\li	'task' is a valid task.
555  * 	If the task has not been named, the string is
561 isc_task_gettag(isc_task_t *task);
563  * Get the tag value for  'task', as previously set using isc_task_settag().
569  *\li	'task' is a valid task.
573 isc_task_beginexclusive(isc_task_t *task);
575  * Request exclusive access for 'task', which must be the calling
576  * task.  Waits for any other concurrently executing tasks to finish their
578  * tasks sharing a task manager with 'task'.
584  *\li	'task' is the calling task.
587  *\li	#ISC_R_SUCCESS		The current task now has exclusive access.
588  *\li	#ISC_R_LOCKBUSY		Another task has already requested exclusive
593 isc_task_endexclusive(isc_task_t *task);
599  *\li	'task' is the calling task, and has obtained
604 isc_task_getcurrenttime(isc_task_t *task, isc_stdtime_t *t);
606  * Provide the most recent timestamp on the task.  The timestamp is considered
610  *\li	'task' is a valid task.
620  * Returns ISC_TRUE if the task is in the process of shutting down,
624  *\li	'task' is a valid task.
628 isc_task_setprivilege(isc_task_t *task, isc_boolean_t priv);
630  * Set or unset the task's "privileged" flag depending on the value of
633  * Under normal circumstances this flag has no effect on the task behavior,
634  * but when the task manager has been set to privileged exeuction mode via
637  * tasks have finished executing, the task manager will automatically
638  * return to normal execution mode and nonprivileged task can resume.
641  *\li	'task' is a valid task.
645 isc_task_privilege(isc_task_t *task);
647  * Returns the current value of the task's privilege flag.
650  *\li	'task' is a valid task.
665  * Create a new task manager.  isc_taskmgr_createinctx() also associates
692  *\li	On success, '*managerp' will be attached to the newly created task
701  *\li	#ISC_R_SHUTTINGDOWN      	The non-threaded, shared, task
711  * Set/get the current operating mode of the task manager.  Valid modes are:
720  * necessary to have at least one privileged task waiting on the ready
722  * which in turn means the task which calls this function should be in
723  * task-exclusive mode when it does so.
727  *\li      'manager' is a valid task manager.
741  *\li	isc_taskmgr_destroy() must not be called by a task event action,
743  *	complete.  An event action that wants to cause task manager shutdown
754  *\li	'*managerp' is a valid task manager.
760  *\li	All resources used by the task manager, and any tasks it managed,
765 isc_taskmgr_setexcltask(isc_taskmgr_t *mgr, isc_task_t *task);
767  * Set a task which will be used for all task-exclusive operations.
770  *\li	'manager' is a valid task manager.
772  *\li	'task' is a valid task.
778  * Attach '*taskp' to the task set by isc_taskmgr_getexcltask().
779  * This task should be used whenever running in task-exclusive mode,
783  *\li	'manager' is a valid task manager.
807  * Register a new task management implementation and add it to the list of
815  * A short cut function that specifies the task management module in the ISC