task.h File Reference

The task system provides a lightweight execution context, which is basically an event queue. More...

#include <isc/eventclass.h>
#include <isc/json.h>
#include <isc/lang.h>
#include <isc/stdtime.h>
#include <isc/types.h>
#include <isc/xml.h>

Go to the source code of this file.

Data Structures
struct	isc_taskmgrmethods
	Task and task manager methods. More...
struct	isc_taskmethods
struct	isc_taskmgr
	This structure is actually just the common prefix of a task manager object implementation's version of an isc_taskmgr_t. More...
struct	isc_task
	This is the common prefix of a task object. The same note as that for the taskmgr structure applies. More...
Defines
#define	ISC_TASK_H   1
#define	ISC_TASKEVENT_FIRSTEVENT   (ISC_EVENTCLASS_TASK + 0)
#define	ISC_TASKEVENT_SHUTDOWN   (ISC_EVENTCLASS_TASK + 1)
#define	ISC_TASKEVENT_TEST   (ISC_EVENTCLASS_TASK + 1)
#define	ISC_TASKEVENT_LASTEVENT   (ISC_EVENTCLASS_TASK + 65535)
#define	ISCAPI_TASKMGR_MAGIC   ISC_MAGIC('A','t','m','g')
#define	ISCAPI_TASKMGR_VALID(m)
#define	ISCAPI_TASK_MAGIC   ISC_MAGIC('A','t','s','t')
#define	ISCAPI_TASK_VALID(s)
Typedefs
typedef struct isc_taskmgrmethods	isc_taskmgrmethods_t
typedef struct isc_taskmethods	isc_taskmethods_t
typedef isc_result_t(*	isc_taskmgrcreatefunc_t )(isc_mem_t *mctx, unsigned int workers, unsigned int default_quantum, isc_taskmgr_t **managerp)
Enumerations
enum	isc_taskmgrmode_t { isc_taskmgrmode_normal = 0, isc_taskmgrmode_privileged }
Functions
isc_result_t	isc_task_create (isc_taskmgr_t *manager, unsigned int quantum, isc_task_t **taskp)
	Create a task.
void	isc_task_attach (isc_task_t *source, isc_task_t **targetp)
	Attach *targetp to source.
void	isc_task_detach (isc_task_t **taskp)
	Detach *taskp from its task.
void	isc_task_send (isc_task_t *task, isc_event_t **eventp)
	Send '*event' to 'task'.
void	isc_task_sendanddetach (isc_task_t **taskp, isc_event_t **eventp)
	Send '*event' to '*taskp' and then detach '*taskp' from its task.
unsigned int	isc_task_purgerange (isc_task_t *task, void *sender, isc_eventtype_t first, isc_eventtype_t last, void *tag)
	Purge events from a task's event queue.
unsigned int	isc_task_purge (isc_task_t *task, void *sender, isc_eventtype_t type, void *tag)
	Purge events from a task's event queue.
isc_boolean_t	isc_task_purgeevent (isc_task_t *task, isc_event_t *event)
	Purge 'event' from a task's event queue.
unsigned int	isc_task_unsendrange (isc_task_t *task, void *sender, isc_eventtype_t first, isc_eventtype_t last, void *tag, isc_eventlist_t *events)
	Remove events from a task's event queue.
unsigned int	isc_task_unsend (isc_task_t *task, void *sender, isc_eventtype_t type, void *tag, isc_eventlist_t *events)
	Remove events from a task's event queue.
isc_result_t	isc_task_onshutdown (isc_task_t *task, isc_taskaction_t action, void *arg)
	Send a shutdown event with action 'action' and argument 'arg' when 'task' is shutdown.
void	isc_task_shutdown (isc_task_t *task)
	Shutdown 'task'.
void	isc_task_destroy (isc_task_t **taskp)
	Destroy '*taskp'.
void	isc_task_setname (isc_task_t *task, const char *name, void *tag)
	Name 'task'.
const char *	isc_task_getname (isc_task_t *task)
	Get the name of 'task', as previously set using isc_task_setname().
void *	isc_task_gettag (isc_task_t *task)
	Get the tag value for 'task', as previously set using isc_task_settag().
isc_result_t	isc_task_beginexclusive (isc_task_t *task)
	Request exclusive access for 'task', which must be the calling task. Waits for any other concurrently executing tasks to finish their current event, and prevents any new events from executing in any of the tasks sharing a task manager with 'task'.
void	isc_task_endexclusive (isc_task_t *task)
	Relinquish the exclusive access obtained by isc_task_beginexclusive(), allowing other tasks to execute.
void	isc_task_getcurrenttime (isc_task_t *task, isc_stdtime_t *t)
	Provide the most recent timestamp on the task. The timestamp is considered as the "current time" in the second-order granularity.
isc_boolean_t	isc_task_exiting (isc_task_t *t)
	Returns ISC_TRUE if the task is in the process of shutting down, ISC_FALSE otherwise.
void	isc_task_setprivilege (isc_task_t *task, isc_boolean_t priv)
	Set or unset the task's "privileged" flag depending on the value of 'priv'.
isc_boolean_t	isc_task_privilege (isc_task_t *task)
	Returns the current value of the task's privilege flag.
isc_result_t	isc_taskmgr_createinctx (isc_mem_t *mctx, isc_appctx_t *actx, unsigned int workers, unsigned int default_quantum, isc_taskmgr_t **managerp)
isc_result_t	isc_taskmgr_create (isc_mem_t *mctx, unsigned int workers, unsigned int default_quantum, isc_taskmgr_t **managerp)
	Create a new task manager. isc_taskmgr_createinctx() also associates the new manager with the specified application context.
void	isc_taskmgr_setmode (isc_taskmgr_t *manager, isc_taskmgrmode_t mode)
isc_taskmgrmode_t	isc_taskmgr_mode (isc_taskmgr_t *manager)
	Set/get the current operating mode of the task manager. Valid modes are:.
void	isc_taskmgr_destroy (isc_taskmgr_t **managerp)
	Destroy '*managerp'.
void	isc_taskmgr_setexcltask (isc_taskmgr_t *mgr, isc_task_t *task)
	Set a task which will be used for all task-exclusive operations.
isc_result_t	isc_taskmgr_excltask (isc_taskmgr_t *mgr, isc_task_t **taskp)
	Attach '*taskp' to the task set by isc_taskmgr_getexcltask(). This task should be used whenever running in task-exclusive mode, so as to prevent deadlock between two exclusive tasks.
isc_result_t	isc_task_register (isc_taskmgrcreatefunc_t createfunc)
	Register a new task management implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.
isc_result_t	isc__task_register (void)
	A short cut function that specifies the task management module in the ISC library for isc_task_register(). An application that uses the ISC library usually do not have to care about this function: it would call isc_lib_register(), which internally calls this function.

---

Detailed Description

The task system provides a lightweight execution context, which is basically an event queue.

When a task's event queue is non-empty, the task is runnable. A small work crew of threads, typically one per CPU, execute runnable tasks by dispatching the events on the tasks' event queues. Context switching between tasks is fast.

• MP: The module ensures appropriate synchronization of data structures it creates and manipulates. The caller must ensure that isc_taskmgr_destroy() is called only once for a given manager.

• Reliability: No anticipated impact.

• Resources: TBS

• Security: No anticipated impact.

• Standards: None.

Purging and Unsending

Events which have been queued for a task but not delivered may be removed from the task's event queue by purging or unsending.

With both types, the caller specifies a matching pattern that selects events based upon their sender, type, and tag.

Purging calls isc_event_free() on the matching events.

Unsending returns a list of events that matched the pattern. The caller is then responsible for them.

Consumers of events should purge, not unsend.

Producers of events often want to remove events when the caller indicates it is no longer interested in the object, e.g. by canceling a timer. Sometimes this can be done by purging, but for some event types, the calls to isc_event_free() cause deadlock because the event free routine wants to acquire a lock the caller is already holding. Unsending instead of purging solves this problem. As a general rule, producers should only unsend events which they have sent.

Definition in file task.h.

---

Define Documentation

#define ISC_TASK_H   1

Definition at line 21 of file task.h.

#define ISC_TASKEVENT_FIRSTEVENT   (ISC_EVENTCLASS_TASK + 0)

Definition at line 90 of file task.h.

#define ISC_TASKEVENT_SHUTDOWN   (ISC_EVENTCLASS_TASK + 1)

Definition at line 91 of file task.h.

Referenced by acache_cleaner_shutdown_action(), cleaner_shutdown_action(), client_shutdown(), and isc__task_onshutdown().

#define ISC_TASKEVENT_TEST   (ISC_EVENTCLASS_TASK + 1)

Definition at line 92 of file task.h.

Referenced by ATF_TC_BODY().

#define ISC_TASKEVENT_LASTEVENT   (ISC_EVENTCLASS_TASK + 65535)

Definition at line 93 of file task.h.

#define ISCAPI_TASKMGR_MAGIC   ISC_MAGIC('A','t','m','g')

Definition at line 161 of file task.h.

Referenced by isc__taskmgr_create().

#define ISCAPI_TASKMGR_VALID

(

m

)

Value:

((m) != NULL && \
                                 (m)->magic == ISCAPI_TASKMGR_MAGIC)

Definition at line 162 of file task.h.

Referenced by isc_task_create(), isc_taskmgr_destroy(), isc_taskmgr_mode(), and isc_taskmgr_setmode().

#define ISCAPI_TASK_MAGIC   ISC_MAGIC('A','t','s','t')

Definition at line 175 of file task.h.

Referenced by isc__task_create().

#define ISCAPI_TASK_VALID

(

s

)

Value:

((s) != NULL && \
                                 (s)->magic == ISCAPI_TASK_MAGIC)

Definition at line 176 of file task.h.

Referenced by ATF_TC_BODY(), isc_task_attach(), isc_task_beginexclusive(), isc_task_detach(), isc_task_endexclusive(), isc_task_onshutdown(), isc_task_privilege(), isc_task_purge(), isc_task_purgerange(), isc_task_send(), isc_task_sendanddetach(), isc_task_setname(), isc_task_setprivilege(), isc_task_shutdown(), and isc_task_unsend().

---

Typedef Documentation

typedef struct isc_taskmgrmethods isc_taskmgrmethods_t

typedef struct isc_taskmethods isc_taskmethods_t

typedef isc_result_t(* isc_taskmgrcreatefunc_t)(isc_mem_t *mctx, unsigned int workers, unsigned int default_quantum, isc_taskmgr_t **managerp)

Definition at line 804 of file task.h.

---

Enumeration Type Documentation

enum isc_taskmgrmode_t

Enumerator:

isc_taskmgrmode_normal
isc_taskmgrmode_privileged

Definition at line 105 of file task.h.

---

Function Documentation

isc_result_t isc_task_create	(	isc_taskmgr_t *	manager,
		unsigned int	quantum,
		isc_task_t **	taskp
	)

Create a task.

Notes:

• If 'quantum' is non-zero, then only that many events can be dispatched before the task must yield to other tasks waiting to execute. If quantum is zero, then the default quantum of the task manager will be used.

• The 'quantum' option may be removed from isc_task_create() in the future. If this happens, isc_task_getquantum() and isc_task_setquantum() will be provided.

Requires:

• 'manager' is a valid task manager.

• taskp != NULL && *taskp == NULL

Ensures:

• On success, '*taskp' is bound to the new task.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_UNEXPECTED
• ISC_R_SHUTTINGDOWN

Definition at line 2108 of file task.c.

References isc__task_create(), isc_bind9, ISCAPI_TASKMGR_VALID, isc_taskmgr::methods, REQUIRE, and isc_taskmgrmethods::taskcreate.

Referenced by add_listener(), ATF_TC_BODY(), cache_cleaner_init(), client_create(), create_managers(), dispatch_createudp(), dns_acache_create(), dns_adb_create(), dns_cache_create3(), dns_client_createx2(), dns_dispatch_createtcp2(), dns_ntatable_create(), dns_resolver_create(), dns_view_createresolver(), dns_zonemgr_create(), isc_taskpool_create(), isc_taskpool_expand(), main(), ns_lwdclientmgr_create(), ns_server_create(), poolinit(), setup_libs(), and setup_system().

void isc_task_attach	(	isc_task_t *	source,
		isc_task_t **	targetp
	)

Attach *targetp to source.

Requires:

• 'source' is a valid task.

• 'targetp' points to a NULL isc_task_t *.

Ensures:

• *targetp is attached to source.

Definition at line 2121 of file task.c.

References isc_taskmethods::attach, ENSURE, isc__task_attach(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, and REQUIRE.

Referenced by ATF_TC_BODY(), dns_adb_createfind2(), dns_adb_whenshutdown(), dns_byaddr_create(), dns_client_startrequest(), dns_client_startresolve(), dns_client_startupdate(), dns_dispatch_addresponse3(), dns_lookup_create(), dns_master_dumpinc3(), dns_master_dumptostreaminc(), dns_request_createraw4(), dns_request_createvia4(), dns_requestmgr_whenshutdown(), dns_resolver_whenshutdown(), dns_validator_create(), dns_zone_gettask(), dns_zone_link(), dns_zone_settask(), fctx_join(), get_dispsocket(), isc__app_ctxonrun(), isc__socket_accept(), isc__timer_create(), isc_httpdmgr_create(), isc_ondestroy_register(), isc_taskpool_gettask(), loadctx_create(), ns_interfacemgr_create(), ns_server_dumpdb(), settask(), xfrin_create(), and zonemgr_getio().

void isc_task_detach

(

isc_task_t **

taskp

)

Detach *taskp from its task.

Requires:

• '*taskp' is a valid task.

Ensures:

• *taskp is NULL.

• If '*taskp' is the last reference to the task, the task is idle (has an empty event queue), and has not been shutdown, the task will be shutdown.

• If '*taskp' is the last reference to the task and the task has been shutdown, all resources used by the task will be freed.

Definition at line 2134 of file task.c.

References ENSURE, isc__task_detach(), isc_bind9, ISCAPI_TASK_VALID, and REQUIRE.

Referenced by add_listener(), assignwork(), ATF_TC_BODY(), cache_cleaner_init(), cache_free(), client_create(), destroy(), destroy_disp(), destroy_dispsocket(), destroy_libs(), destroyclient(), dispatch_createudp(), dns_acache_create(), dns_adb_create(), dns_byaddr_create(), dns_cache_create3(), dns_client_createx2(), dns_client_startrequest(), dns_client_startresolve(), dns_client_startupdate(), dns_dispatch_addresponse3(), dns_dispatch_createtcp2(), dns_dispatch_removeresponse(), dns_lookup_create(), dns_ntatable_create(), dns_ntatable_detach(), dns_request_createraw4(), dns_request_createvia4(), dns_resolver_create(), dns_validator_create(), dns_view_createresolver(), dns_zone_settask(), dns_zonemgr_create(), dns_zonemgr_managezone(), doshutdown(), dumpcontext_destroy(), dumpctx_destroy(), exit_check(), fctx_join(), forward_action(), free_rbtdb(), httpdmgr_destroy(), isc__socket_accept(), isc__task_destroy(), isc__timer_create(), isc_httpdmgr_create(), isc_taskpool_destroy(), isc_test_end(), loadctx_destroy(), lwdclientmgr_destroy(), main(), maybe_free(), ns_interfacemgr_create(), ns_interfacemgr_destroy(), ns_interfacemgr_shutdown(), ns_lwdclientmgr_create(), settask(), shutdown_server(), update_action(), xfrin_create(), zone_free(), and zonemgr_putio().

void isc_task_send	(	isc_task_t *	task,
		isc_event_t **	eventp
	)

Send '*event' to 'task'.

Requires:

• 'task' is a valid task.
• eventp != NULL && *eventp != NULL.

Ensures:

• *eventp == NULL.

Definition at line 2146 of file task.c.

References ENSURE, isc__task_send(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, REQUIRE, and isc_taskmethods::send.

Referenced by acache_incremental_cleaning_action(), assignwork(), ATF_TC_BODY(), begin_cleaning(), check_exit(), cleanup_dead_nodes_callback(), closeversion(), decrement_reference(), dighost_shutdown(), dispatch(), dlv_validator_start(), dns_acache_shutdown(), dns_adb_shutdown(), dns_adb_whenshutdown(), dns_dispatch_addresponse3(), dns_dispatch_detach(), dns_dispatch_importrecv(), dns_dispatch_removeresponse(), dns_request_cancel(), dns_requestmgr_whenshutdown(), dns_resolver_createfetch3(), dns_resolver_whenshutdown(), dns_validator_create(), dns_validator_send(), dns_zone_asyncload(), dns_zone_detach(), do_cancel(), done_update(), dump_quantum(), fctx_shutdown(), force_timeout(), forward_action(), forward_callback(), free_rbtdb(), get_client(), get_worker(), incremental_cleaning_action(), isc_ratelimiter_enqueue(), isc_ratelimiter_shutdown(), load_quantum(), new_adbentry(), new_adbname(), ns_server_reloadwanted(), ratelimiter_tick(), receive_secure_serial(), recv_length(), recv_message(), send_forward_event(), send_recvdone_event(), send_senddone_event(), send_update_event(), sign(), task_send(), tcp_recv(), udp_recv(), update_action(), water(), zmgr_start_xfrin_ifquota(), zone_send_securedb(), zone_send_secureserial(), zonemgr_cancelio(), zonemgr_getio(), and zonemgr_putio().

void isc_task_sendanddetach	(	isc_task_t **	taskp,
		isc_event_t **	eventp
	)

Send '*event' to '*taskp' and then detach '*taskp' from its task.

Requires:

• '*taskp' is a valid task.
• eventp != NULL && *eventp != NULL.

Ensures:

• *eventp == NULL.

• *taskp == NULL.

• If '*taskp' is the last reference to the task, the task is idle (has an empty event queue), and has not been shutdown, the task will be shutdown.

• If '*taskp' is the last reference to the task and the task has been shutdown, all resources used by the task will be freed.

Definition at line 2159 of file task.c.

References ENSURE, isc__task_sendanddetach(), isc_bind9, ISCAPI_TASK_VALID, and REQUIRE.

Referenced by clean_finds_at_name(), client_resfind(), dec_adb_irefcnt(), dns_adb_cancelfind(), dns_resolver_cancelfetch(), fctx_sendevents(), internal_accept(), isc__app_ctxrun(), isc__socket_cancel(), isc_ondestroy_notify(), lookup_done(), lookup_find(), req_sendevent(), request_done(), send_connectdone_event(), send_recvdone_event(), send_senddone_event(), send_shutdown_events(), update_sendevent(), and validator_done().

unsigned int isc_task_purgerange	(	isc_task_t *	task,
		void *	sender,
		isc_eventtype_t	first,
		isc_eventtype_t	last,
		void *	tag
	)

Purge events from a task's event queue.

Requires:

• 'task' is a valid task.

• last >= first

Ensures:

• Events in the event queue of 'task' whose sender is 'sender', whose type is >= first and <= last, and whose tag is 'tag' will be purged, unless they are marked as unpurgable.

• A sender of NULL will match any sender. A NULL tag matches any tag.

Returns:

• The number of events purged.

Definition at line 2288 of file task.c.

References isc__task_purgerange(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, isc_taskmethods::purgerange, and REQUIRE.

Referenced by destroy(), and isc__timer_reset().

unsigned int isc_task_purge	(	isc_task_t *	task,
		void *	sender,
		isc_eventtype_t	type,
		void *	tag
	)

Purge events from a task's event queue.

Notes:

• This function is equivalent to

                isc_task_purgerange(task, sender, type, type, tag);
 *

Requires:

• 'task' is a valid task.

Ensures:

• Events in the event queue of 'task' whose sender is 'sender', whose type is 'type', and whose tag is 'tag' will be purged, unless they are marked as unpurgable.

• A sender of NULL will match any sender. A NULL tag matches any tag.

Returns:

• The number of events purged.

Definition at line 2225 of file task.c.

References isc__task_purge(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, isc_taskmethods::purgeevents, and REQUIRE.

Referenced by acache_cleaner_shutdown_action(), and cleaner_shutdown_action().

isc_boolean_t isc_task_purgeevent	(	isc_task_t *	task,
		isc_event_t *	event
	)

Purge 'event' from a task's event queue.

XXXRTH: WARNING: This method may be removed before beta.

Notes:

• If 'event' is on the task's event queue, it will be purged, unless it is marked as unpurgeable. 'event' does not have to be on the task's event queue; in fact, it can even be an invalid pointer. Purging only occurs if the event is actually on the task's event queue.

• Purging never changes the state of the task.

Requires:

• 'task' is a valid task.

Ensures:

• 'event' is not in the event queue for 'task'.

Returns:

• ISC_TRUE The event was purged.
• ISC_FALSE The event was not in the event queue, or was marked unpurgeable.

Definition at line 734 of file task.c.

References DEQUEUE, isc__task::events, HEAD, isc_event_free(), ISC_FALSE, ISC_TRUE, isc__task::lock, LOCK, isc__task::nevents, NEXT, PURGE_OK, REQUIRE, UNLOCK, and VALID_TASK.

unsigned int isc_task_unsendrange	(	isc_task_t *	task,
		void *	sender,
		isc_eventtype_t	first,
		isc_eventtype_t	last,
		void *	tag,
		isc_eventlist_t *	events
	)

Remove events from a task's event queue.

Requires:

• 'task' is a valid task.

• last >= first.

• *events is a valid list.

Ensures:

• Events in the event queue of 'task' whose sender is 'sender', whose type is >= first and <= last, and whose tag is 'tag' will be dequeued and appended to *events.

• A sender of NULL will match any sender. A NULL tag matches any tag.

Returns:

• The number of events unsent.

unsigned int isc_task_unsend	(	isc_task_t *	task,
		void *	sender,
		isc_eventtype_t	type,
		void *	tag,
		isc_eventlist_t *	events
	)

Remove events from a task's event queue.

Notes:

• This function is equivalent to

                isc_task_unsendrange(task, sender, type, type, tag, events);
 *

Requires:

• 'task' is a valid task.

• *events is a valid list.

Ensures:

• Events in the event queue of 'task' whose sender is 'sender', whose type is 'type', and whose tag is 'tag' will be dequeued and appended to *events.

Returns:

• The number of events unsent.

Definition at line 2174 of file task.c.

References isc__task_unsend(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, REQUIRE, and isc_taskmethods::unsend.

Referenced by dns_dispatch_removeresponse().

isc_result_t isc_task_onshutdown	(	isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Send a shutdown event with action 'action' and argument 'arg' when 'task' is shutdown.

Notes:

• Shutdown events are posted in LIFO order.

Requires:

• 'task' is a valid task.

• 'action' is a valid task action.

Ensures:

• When the task is shutdown, shutdown events requested with isc_task_onshutdown() will be appended to the task's event queue.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_TASKSHUTTINGDOWN Task is shutting down.

Definition at line 2186 of file task.c.

References isc__task_onshutdown(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, isc_taskmethods::onshutdown, and REQUIRE.

Referenced by acache_cleaner_init(), cache_cleaner_init(), client_create(), ns_lwdclientmgr_create(), ns_server_create(), and setup_system().

void isc_task_shutdown

(

isc_task_t *

task

)

Shutdown 'task'.

Notes:

• Shutting down a task causes any shutdown events requested with isc_task_onshutdown() to be posted (in LIFO order). The task moves into a "shutting down" mode which prevents further calls to isc_task_onshutdown().

• Trying to shutdown a task that has already been shutdown has no effect.

Requires:

• 'task' is a valid task.

Ensures:

• Any shutdown events requested with isc_task_onshutdown() have been posted (in LIFO order).

Definition at line 2197 of file task.c.

References isc__task_shutdown(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, REQUIRE, and isc_taskmethods::shutdown.

Referenced by client_request(), destroy(), dispatch_createudp(), dns_acache_detach(), dns_cache_detach(), dns_resolver_create(), exit_check(), isc__task_destroy(), listener_shutdown(), ns_clientmgr_destroy(), rndc_recvdone(), and rndc_senddone().

void isc_task_destroy

(

isc_task_t **

taskp

)

Destroy '*taskp'.

Notes:

• This call is equivalent to:

                isc_task_shutdown(*taskp);
                isc_task_detach(taskp);
 *

Requires:

'*taskp' is a valid task.

Ensures:

• Any shutdown events requested with isc_task_onshutdown() have been posted (in LIFO order).

• *taskp == NULL

• If '*taskp' is the last reference to the task, all resources used by the task will be freed.

Definition at line 2207 of file task.c.

References isc__task_destroy(), and isc_bind9.

Referenced by ATF_TC_BODY(), cleanup_managers(), dns_zonemgr_shutdown(), and poolfree().

void isc_task_setname	(	isc_task_t *	task,
		const char *	name,
		void *	tag
	)

Name 'task'.

Notes:

• Only the first 15 characters of 'name' will be copied.

• Naming a task is currently only useful for debugging purposes.

Requires:

• 'task' is a valid task.

Definition at line 2215 of file task.c.

References isc__task_setname(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, REQUIRE, and isc_taskmethods::setname.

Referenced by add_listener(), ATF_TC_BODY(), cache_cleaner_init(), client_create(), dispatch_createudp(), dns_acache_create(), dns_adb_create(), dns_cache_create3(), dns_dispatch_createtcp2(), dns_ntatable_create(), dns_resolver_create(), dns_view_createresolver(), dns_zonemgr_create(), dns_zonemgr_managezone(), isc_taskpool_create(), isc_taskpool_expand(), ns_lwdclientmgr_create(), ns_server_create(), and setup_libs().

const char* isc_task_getname

(

isc_task_t *

task

)

Get the name of 'task', as previously set using isc_task_setname().

Notes:

• This function is for debugging purposes only.

Requires:

• 'task' is a valid task.

Returns:

• A non-NULL pointer to a null-terminated string. If the task has not been named, the string is empty.

void* isc_task_gettag

(

isc_task_t *

task

)

Get the tag value for 'task', as previously set using isc_task_settag().

Notes:

• This function is for debugging purposes only.

Requires:

• 'task' is a valid task.

isc_result_t isc_task_beginexclusive

(

isc_task_t *

task

)

Request exclusive access for 'task', which must be the calling task. Waits for any other concurrently executing tasks to finish their current event, and prevents any new events from executing in any of the tasks sharing a task manager with 'task'.

The exclusive access must be relinquished by calling isc_task_endexclusive() before returning from the current event handler.

Requires:

• 'task' is the calling task.

Returns:

• ISC_R_SUCCESS The current task now has exclusive access.
• ISC_R_LOCKBUSY Another task has already requested exclusive access.

Definition at line 2236 of file task.c.

References isc_taskmethods::beginexclusive, isc__task_beginexclusive(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, and REQUIRE.

Referenced by do_addzone(), do_modzone(), grow_entries(), grow_names(), interface_timer_tick(), load_configuration(), load_new_zones(), load_zones(), ns_clientmgr_destroy(), ns_server_delzone(), ns_server_flushcache(), ns_server_flushnode(), ns_server_freeze(), ns_server_nta(), ns_server_scan_interfaces(), ns_server_showzone(), ns_server_sync(), ns_server_tsigdelete(), ns_server_tsiglist(), ns_server_validation(), and shutdown_server().

void isc_task_endexclusive

(

isc_task_t *

task

)

Relinquish the exclusive access obtained by isc_task_beginexclusive(), allowing other tasks to execute.

Requires:

• 'task' is the calling task, and has obtained exclusive access by calling isc_task_spl().

Definition at line 2246 of file task.c.

References isc_taskmethods::endexclusive, isc__task_endexclusive(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, and REQUIRE.

Referenced by do_addzone(), do_modzone(), grow_entries(), grow_names(), interface_timer_tick(), load_configuration(), load_new_zones(), load_zones(), ns_clientmgr_destroy(), ns_server_delzone(), ns_server_flushcache(), ns_server_flushnode(), ns_server_freeze(), ns_server_nta(), ns_server_scan_interfaces(), ns_server_showzone(), ns_server_sync(), ns_server_tsigdelete(), ns_server_tsiglist(), ns_server_validation(), and shutdown_server().

void isc_task_getcurrenttime	(	isc_task_t *	task,
		isc_stdtime_t *	t
	)

Provide the most recent timestamp on the task. The timestamp is considered as the "current time" in the second-order granularity.

Requires:

• 'task' is a valid task.
• 't' is a valid non NULL pointer.

Ensures:

• '*t' has the "current time".

Definition at line 2276 of file task.c.

References isc__task_getcurrenttime(), and isc_bind9.

Referenced by client_request().

isc_boolean_t isc_task_exiting

(

isc_task_t *

t

)

Returns ISC_TRUE if the task is in the process of shutting down, ISC_FALSE otherwise.

Requires:

• 'task' is a valid task.

Definition at line 1785 of file task.c.

References REQUIRE, TASK_SHUTTINGDOWN, and VALID_TASK.

Referenced by isc__socket_accept().

void isc_task_setprivilege	(	isc_task_t *	task,
		isc_boolean_t	priv
	)

Set or unset the task's "privileged" flag depending on the value of 'priv'.

Under normal circumstances this flag has no effect on the task behavior, but when the task manager has been set to privileged execution mode via isc_taskmgr_setmode(), only tasks with the flag set will be executed, and all other tasks will wait until they're done. Once all privileged tasks have finished executing, the task manager will automatically return to normal execution mode and nonprivileged task can resume.

Requires:

• 'task' is a valid task.

Definition at line 2256 of file task.c.

References isc__task_setprivilege(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, REQUIRE, and isc_taskmethods::setprivilege.

Referenced by ATF_TC_BODY(), and isc_taskpool_setprivilege().

isc_boolean_t isc_task_privilege

(

isc_task_t *

task

)

Returns the current value of the task's privilege flag.

Requires:

• 'task' is a valid task.

Definition at line 2266 of file task.c.

References isc__task_privilege(), isc_bind9, ISCAPI_TASK_VALID, isc_task::methods, isc_taskmethods::privilege, and REQUIRE.

Referenced by ATF_TC_BODY().

isc_result_t isc_taskmgr_createinctx	(	isc_mem_t *	mctx,
		isc_appctx_t *	actx,
		unsigned int	workers,
		unsigned int	default_quantum,
		isc_taskmgr_t **	managerp
	)

Definition at line 2035 of file task.c.

References isc_appctx_settaskmgr(), ISC_R_SUCCESS, LOCK, REQUIRE, and UNLOCK.

Referenced by dns_client_create().

isc_result_t isc_taskmgr_create	(	isc_mem_t *	mctx,
		unsigned int	workers,
		unsigned int	default_quantum,
		isc_taskmgr_t **	managerp
	)

Create a new task manager. isc_taskmgr_createinctx() also associates the new manager with the specified application context.

Notes:

• 'workers' in the number of worker threads to create. In general, the value should be close to the number of processors in the system. The 'workers' value is advisory only. An attempt will be made to create 'workers' threads, but if at least one thread creation succeeds, isc_taskmgr_create() may return ISC_R_SUCCESS.

• If 'default_quantum' is non-zero, then it will be used as the default quantum value when tasks are created. If zero, then an implementation defined default quantum will be used.

Requires:

• 'mctx' is a valid memory context.

• workers > 0

• managerp != NULL && *managerp == NULL

• 'actx' is a valid application context (for createinctx()).

Ensures:

• On success, '*managerp' will be attached to the newly created task manager.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_NOTHREADS No threads could be created.
• ISC_R_UNEXPECTED An unexpected error occurred.
• ISC_R_SHUTTINGDOWN The non-threaded, shared, task manager shutting down.

Definition at line 2056 of file task.c.

References isc__taskmgr_create(), isc_bind9, LOCK, REQUIRE, and UNLOCK.

Referenced by create_managers(), main(), setup_libs(), and setup_system().

void isc_taskmgr_setmode	(	isc_taskmgr_t *	manager,
		isc_taskmgrmode_t	mode
	)

Definition at line 2088 of file task.c.

References isc__taskmgr_setmode(), isc_bind9, ISCAPI_TASKMGR_VALID, isc_taskmgr::methods, REQUIRE, and isc_taskmgrmethods::setmode.

Referenced by ATF_TC_BODY(), load_zones(), and set_and_drop().

isc_taskmgrmode_t isc_taskmgr_mode

(

isc_taskmgr_t *

manager

)

Set/get the current operating mode of the task manager. Valid modes are:.

• isc_taskmgrmode_normal
• isc_taskmgrmode_privileged

In privileged execution mode, only tasks that have had the "privilege" flag set via isc_task_setprivilege() can be executed. When all such tasks are complete, the manager automatically returns to normal mode and proceeds with running non-privileged ready tasks. This means it is necessary to have at least one privileged task waiting on the ready queue *before* setting the manager into privileged execution mode, which in turn means the task which calls this function should be in task-exclusive mode when it does so.

Requires:

• 'manager' is a valid task manager.

Definition at line 2098 of file task.c.

References isc__taskmgr_mode(), isc_bind9, ISCAPI_TASKMGR_VALID, isc_taskmgr::methods, isc_taskmgrmethods::mode, and REQUIRE.

Referenced by ATF_TC_BODY(), and set_and_drop().

void isc_taskmgr_destroy

(

isc_taskmgr_t **

managerp

)

Destroy '*managerp'.

Notes:

• Calling isc_taskmgr_destroy() will shutdown all tasks managed by *managerp that haven't already been shutdown. The call will block until all tasks have entered the done state.

• isc_taskmgr_destroy() must not be called by a task event action, because it would block forever waiting for the event action to complete. An event action that wants to cause task manager shutdown should request some non-event action thread of execution to do the shutdown, e.g. by signaling a condition variable or using isc_app_shutdown().

• Task manager references are not reference counted, so the caller must ensure that no attempt will be made to use the manager after isc_taskmgr_destroy() returns.

Requires:

• '*managerp' is a valid task manager.

• isc_taskmgr_destroy() has not be called previously on '*managerp'.

Ensures:

• All resources used by the task manager, and any tasks it managed, have been freed.

Definition at line 2076 of file task.c.

References ENSURE, isc__taskmgr_destroy(), isc_bind9, ISCAPI_TASKMGR_VALID, and REQUIRE.

Referenced by cleanup(), cleanup_managers(), destroy_libs(), destroy_managers(), destroyclient(), dns_client_create(), isc_test_end(), and main().

void isc_taskmgr_setexcltask	(	isc_taskmgr_t *	mgr,
		isc_task_t *	task
	)

Set a task which will be used for all task-exclusive operations.

Requires:

• 'manager' is a valid task manager.

• 'task' is a valid task.

Definition at line 1668 of file task.c.

References isc__task_attach(), isc__task_detach(), LOCK, REQUIRE, UNLOCK, VALID_MANAGER, and VALID_TASK.

Referenced by create_managers(), and ns_server_create().

isc_result_t isc_taskmgr_excltask	(	isc_taskmgr_t *	mgr,
		isc_task_t **	taskp
	)

Attach '*taskp' to the task set by isc_taskmgr_getexcltask(). This task should be used whenever running in task-exclusive mode, so as to prevent deadlock between two exclusive tasks.

Requires:

• 'manager' is a valid task manager.

• taskp != NULL && *taskp == NULL See isc_taskmgr_create() above.

Definition at line 1682 of file task.c.

References isc__task_attach(), ISC_R_NOTFOUND, ISC_R_SUCCESS, LOCK, REQUIRE, UNLOCK, and VALID_MANAGER.

Referenced by dns_adb_create().

isc_result_t isc_task_register

(

isc_taskmgrcreatefunc_t

createfunc

)

Register a new task management implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.

Definition at line 2019 of file task.c.

References initialize(), isc_once_do, ISC_R_EXISTS, ISC_R_SUCCESS, LOCK, RUNTIME_CHECK, and UNLOCK.

Referenced by isc__task_register().

isc_result_t isc__task_register

(

void

)

A short cut function that specifies the task management module in the ISC library for isc_task_register(). An application that uses the ISC library usually do not have to care about this function: it would call isc_lib_register(), which internally calls this function.

Definition at line 1780 of file task.c.

References isc__taskmgr_create(), and isc_task_register().

Referenced by do_register().

---