2 * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2001, 2003 Internet Software Consortium.
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: task.h,v 1.51.18.2 2005/04/29 00:17:03 marka Exp $ */
28 * \brief The task system provides a lightweight execution context, which is
29 * basically an event queue.
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,
33 * execute runnable tasks by dispatching the events on the tasks' event
34 * queues. Context switching between tasks is fast.
37 * The module ensures appropriate synchronization of data structures it
38 * creates and manipulates.
39 * The caller must ensure that isc_taskmgr_destroy() is called only
40 * once for a given manager.
43 * No anticipated impact.
49 * No anticipated impact.
54 * \section purge Purging and Unsending
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.
59 * With both types, the caller specifies a matching pattern that selects
60 * events based upon their sender, type, and tag.
62 * Purging calls isc_event_free() on the matching events.
64 * Unsending returns a list of events that matched the pattern.
65 * The caller is then responsible for them.
67 * Consumers of events should purge, not unsend.
69 * Producers of events often want to remove events when the caller indicates
70 * it is no longer interested in the object, e.g. by cancelling a timer.
71 * Sometimes this can be done by purging, but for some event types, the
72 * calls to isc_event_free() cause deadlock because the event free routine
73 * wants to acquire a lock the caller is already holding. Unsending instead
74 * of purging solves this problem. As a general rule, producers should only
75 * unsend events which they have sent.
83 #include <isc/eventclass.h>
85 #include <isc/stdtime.h>
86 #include <isc/types.h>
88 #define ISC_TASKEVENT_FIRSTEVENT (ISC_EVENTCLASS_TASK + 0)
89 #define ISC_TASKEVENT_SHUTDOWN (ISC_EVENTCLASS_TASK + 1)
90 #define ISC_TASKEVENT_LASTEVENT (ISC_EVENTCLASS_TASK + 65535)
99 isc_task_create(isc_taskmgr_t *manager, unsigned int quantum,
106 *\li If 'quantum' is non-zero, then only that many events can be dispatched
107 * before the task must yield to other tasks waiting to execute. If
108 * quantum is zero, then the default quantum of the task manager will
111 *\li The 'quantum' option may be removed from isc_task_create() in the
112 * future. If this happens, isc_task_getquantum() and
113 * isc_task_setquantum() will be provided.
117 *\li 'manager' is a valid task manager.
119 *\li taskp != NULL && *taskp == NULL
123 *\li On success, '*taskp' is bound to the new task.
129 *\li #ISC_R_UNEXPECTED
130 *\li #ISC_R_SHUTTINGDOWN
134 isc_task_attach(isc_task_t *source, isc_task_t **targetp);
136 * Attach *targetp to source.
140 *\li 'source' is a valid task.
142 *\li 'targetp' points to a NULL isc_task_t *.
146 *\li *targetp is attached to source.
150 isc_task_detach(isc_task_t **taskp);
152 * Detach *taskp from its task.
156 *\li '*taskp' is a valid task.
162 *\li If '*taskp' is the last reference to the task, the task is idle (has
163 * an empty event queue), and has not been shutdown, the task will be
166 *\li If '*taskp' is the last reference to the task and
167 * the task has been shutdown,
168 * all resources used by the task will be freed.
172 isc_task_send(isc_task_t *task, isc_event_t **eventp);
174 * Send '*event' to 'task'.
178 *\li 'task' is a valid task.
179 *\li eventp != NULL && *eventp != NULL.
183 *\li *eventp == NULL.
187 isc_task_sendanddetach(isc_task_t **taskp, isc_event_t **eventp);
189 * Send '*event' to '*taskp' and then detach '*taskp' from its
194 *\li '*taskp' is a valid task.
195 *\li eventp != NULL && *eventp != NULL.
199 *\li *eventp == NULL.
203 *\li If '*taskp' is the last reference to the task, the task is
204 * idle (has an empty event queue), and has not been shutdown,
205 * the task will be shutdown.
207 *\li If '*taskp' is the last reference to the task and
208 * the task has been shutdown,
209 * all resources used by the task will be freed.
214 isc_task_purgerange(isc_task_t *task, void *sender, isc_eventtype_t first,
215 isc_eventtype_t last, void *tag);
217 * Purge events from a task's event queue.
221 *\li 'task' is a valid task.
227 *\li Events in the event queue of 'task' whose sender is 'sender', whose
228 * type is >= first and <= last, and whose tag is 'tag' will be purged,
229 * unless they are marked as unpurgable.
231 *\li A sender of NULL will match any sender. A NULL tag matches any
236 *\li The number of events purged.
240 isc_task_purge(isc_task_t *task, void *sender, isc_eventtype_t type,
243 * Purge events from a task's event queue.
247 *\li This function is equivalent to
250 * isc_task_purgerange(task, sender, type, type, tag);
255 *\li 'task' is a valid task.
259 *\li Events in the event queue of 'task' whose sender is 'sender', whose
260 * type is 'type', and whose tag is 'tag' will be purged, unless they
261 * are marked as unpurgable.
263 *\li A sender of NULL will match any sender. A NULL tag matches any
268 *\li The number of events purged.
272 isc_task_purgeevent(isc_task_t *task, isc_event_t *event);
274 * Purge 'event' from a task's event queue.
276 * XXXRTH: WARNING: This method may be removed before beta.
280 *\li If 'event' is on the task's event queue, it will be purged,
281 * unless it is marked as unpurgeable. 'event' does not have to be
282 * on the task's event queue; in fact, it can even be an invalid
283 * pointer. Purging only occurs if the event is actually on the task's
286 * \li Purging never changes the state of the task.
290 *\li 'task' is a valid task.
294 *\li 'event' is not in the event queue for 'task'.
298 *\li #ISC_TRUE The event was purged.
299 *\li #ISC_FALSE The event was not in the event queue,
300 * or was marked unpurgeable.
304 isc_task_unsendrange(isc_task_t *task, void *sender, isc_eventtype_t first,
305 isc_eventtype_t last, void *tag, isc_eventlist_t *events);
307 * Remove events from a task's event queue.
311 *\li 'task' is a valid task.
315 *\li *events is a valid list.
319 *\li Events in the event queue of 'task' whose sender is 'sender', whose
320 * type is >= first and <= last, and whose tag is 'tag' will be dequeued
321 * and appended to *events.
323 *\li A sender of NULL will match any sender. A NULL tag matches any
328 *\li The number of events unsent.
332 isc_task_unsend(isc_task_t *task, void *sender, isc_eventtype_t type,
333 void *tag, isc_eventlist_t *events);
335 * Remove events from a task's event queue.
339 *\li This function is equivalent to
342 * isc_task_unsendrange(task, sender, type, type, tag, events);
347 *\li 'task' is a valid task.
349 *\li *events is a valid list.
353 *\li Events in the event queue of 'task' whose sender is 'sender', whose
354 * type is 'type', and whose tag is 'tag' will be dequeued and appended
359 *\li The number of events unsent.
363 isc_task_onshutdown(isc_task_t *task, isc_taskaction_t action,
366 * Send a shutdown event with action 'action' and argument 'arg' when
367 * 'task' is shutdown.
371 *\li Shutdown events are posted in LIFO order.
375 *\li 'task' is a valid task.
377 *\li 'action' is a valid task action.
381 *\li When the task is shutdown, shutdown events requested with
382 * isc_task_onshutdown() will be appended to the task's event queue.
389 *\li #ISC_R_TASKSHUTTINGDOWN Task is shutting down.
393 isc_task_shutdown(isc_task_t *task);
399 *\li Shutting down a task causes any shutdown events requested with
400 * isc_task_onshutdown() to be posted (in LIFO order). The task
401 * moves into a "shutting down" mode which prevents further calls
402 * to isc_task_onshutdown().
404 *\li Trying to shutdown a task that has already been shutdown has no
409 *\li 'task' is a valid task.
413 *\li Any shutdown events requested with isc_task_onshutdown() have been
414 * posted (in LIFO order).
418 isc_task_destroy(isc_task_t **taskp);
424 *\li This call is equivalent to:
427 * isc_task_shutdown(*taskp);
428 * isc_task_detach(taskp);
433 * '*taskp' is a valid task.
437 *\li Any shutdown events requested with isc_task_onshutdown() have been
438 * posted (in LIFO order).
442 *\li If '*taskp' is the last reference to the task,
443 * all resources used by the task will be freed.
447 isc_task_setname(isc_task_t *task, const char *name, void *tag);
453 *\li Only the first 15 characters of 'name' will be copied.
455 *\li Naming a task is currently only useful for debugging purposes.
459 *\li 'task' is a valid task.
463 isc_task_getname(isc_task_t *task);
465 * Get the name of 'task', as previously set using isc_task_setname().
468 *\li This function is for debugging purposes only.
471 *\li 'task' is a valid task.
474 *\li A non-NULL pointer to a null-terminated string.
475 * If the task has not been named, the string is
481 isc_task_gettag(isc_task_t *task);
483 * Get the tag value for 'task', as previously set using isc_task_settag().
486 *\li This function is for debugging purposes only.
489 *\li 'task' is a valid task.
493 isc_task_beginexclusive(isc_task_t *task);
495 * Request exclusive access for 'task', which must be the calling
496 * task. Waits for any other concurrently executing tasks to finish their
497 * current event, and prevents any new events from executing in any of the
498 * tasks sharing a task manager with 'task'.
500 * The exclusive access must be relinquished by calling
501 * isc_task_endexclusive() before returning from the current event handler.
504 *\li 'task' is the calling task.
507 *\li #ISC_R_SUCCESS The current task now has exclusive access.
508 *\li #ISC_R_LOCKBUSY Another task has already requested exclusive
513 isc_task_endexclusive(isc_task_t *task);
515 * Relinquish the exclusive access obtained by isc_task_beginexclusive(),
516 * allowing other tasks to execute.
519 *\li 'task' is the calling task, and has obtained
520 * exclusive access by calling isc_task_spl().
524 isc_task_getcurrenttime(isc_task_t *task, isc_stdtime_t *t);
526 * Provide the most recent timestamp on the task. The timestamp is considered
527 * as the "current time" in the second-order granularity.
530 *\li 'task' is a valid task.
531 *\li 't' is a valid non NULL pointer.
534 *\li '*t' has the "current time".
542 isc_taskmgr_create(isc_mem_t *mctx, unsigned int workers,
543 unsigned int default_quantum, isc_taskmgr_t **managerp);
545 * Create a new task manager.
549 *\li 'workers' in the number of worker threads to create. In general,
550 * the value should be close to the number of processors in the system.
551 * The 'workers' value is advisory only. An attempt will be made to
552 * create 'workers' threads, but if at least one thread creation
553 * succeeds, isc_taskmgr_create() may return ISC_R_SUCCESS.
555 *\li If 'default_quantum' is non-zero, then it will be used as the default
556 * quantum value when tasks are created. If zero, then an implementation
557 * defined default quantum will be used.
561 *\li 'mctx' is a valid memory context.
565 *\li managerp != NULL && *managerp == NULL
569 *\li On success, '*managerp' will be attached to the newly created task
576 *\li #ISC_R_NOTHREADS No threads could be created.
577 *\li #ISC_R_UNEXPECTED An unexpected error occurred.
581 isc_taskmgr_destroy(isc_taskmgr_t **managerp);
583 * Destroy '*managerp'.
587 *\li Calling isc_taskmgr_destroy() will shutdown all tasks managed by
588 * *managerp that haven't already been shutdown. The call will block
589 * until all tasks have entered the done state.
591 *\li isc_taskmgr_destroy() must not be called by a task event action,
592 * because it would block forever waiting for the event action to
593 * complete. An event action that wants to cause task manager shutdown
594 * should request some non-event action thread of execution to do the
595 * shutdown, e.g. by signalling a condition variable or using
596 * isc_app_shutdown().
598 *\li Task manager references are not reference counted, so the caller
599 * must ensure that no attempt will be made to use the manager after
600 * isc_taskmgr_destroy() returns.
604 *\li '*managerp' is a valid task manager.
606 *\li isc_taskmgr_destroy() has not be called previously on '*managerp'.
610 *\li All resources used by the task manager, and any tasks it managed,
616 #endif /* ISC_TASK_H */