FM / isc

/usr/include/bind9/isc

Name	Size	Mode	Actions
aes.h	1015	0644	edit dl rm
align.h	569	0644	edit dl rm
app.h	7139	0644	edit dl rm
assertions.h	2227	0644	edit dl rm
astack.h	1137	0644	edit dl rm
atomic.h	3082	0644	edit dl rm
backtrace.h	3894	0644	edit dl rm
barrier.h	1052	0644	edit dl rm
base32.h	4453	0644	edit dl rm
base64.h	2865	0644	edit dl rm
bind9.h	829	0644	edit dl rm
buffer.h	30625	0644	edit dl rm
bufferlist.h	1453	0644	edit dl rm
cmocka.h	1383	0644	edit dl rm
commandline.h	1711	0644	edit dl rm
condition.h	1914	0644	edit dl rm
counter.h	1922	0644	edit dl rm
crc64.h	998	0644	edit dl rm
deprecated.h	662	0644	edit dl rm
dir.h	1545	0644	edit dl rm
endian.h	4868	0644	edit dl rm
errno.h	659	0644	edit dl rm
errno2result.h	901	0644	edit dl rm
error.h	1434	0644	edit dl rm
event.h	3442	0644	edit dl rm
eventclass.h	1442	0644	edit dl rm
file.h	11669	0644	edit dl rm
formatcheck.h	940	0644	edit dl rm
fsaccess.h	7453	0644	edit dl rm
fuzz.h	593	0644	edit dl rm
hash.h	1649	0644	edit dl rm
heap.h	5263	0644	edit dl rm
hex.h	2805	0644	edit dl rm
hmac.h	3970	0644	edit dl rm
hp.h	4588	0644	edit dl rm
ht.h	4485	0644	edit dl rm
httpd.h	2291	0644	edit dl rm
interfaceiter.h	3141	0644	edit dl rm
iterated_hash.h	933	0644	edit dl rm
lang.h	686	0644	edit dl rm
lex.h	10004	0644	edit dl rm
lfsr.h	2955	0644	edit dl rm
lib.h	1155	0644	edit dl rm
likely.h	868	0644	edit dl rm
list.h	8085	0644	edit dl rm
log.h	26497	0644	edit dl rm
magic.h	999	0644	edit dl rm
managers.h	776	0644	edit dl rm
md.h	5760	0644	edit dl rm
mem.h	18086	0644	edit dl rm
meminfo.h	710	0644	edit dl rm
mutex.h	4178	0644	edit dl rm
mutexatomic.h	9790	0644	edit dl rm
mutexblock.h	1162	0644	edit dl rm
net.h	8564	0644	edit dl rm
netaddr.h	4786	0644	edit dl rm
netdb.h	860	0644	edit dl rm
netmgr.h	15732	0644	edit dl rm
netscope.h	966	0644	edit dl rm
nonce.h	743	0644	edit dl rm
offset.h	687	0644	edit dl rm
once.h	767	0644	edit dl rm
os.h	765	0644	edit dl rm
parseint.h	1541	0644	edit dl rm
platform.h	1859	0644	edit dl rm
pool.h	3491	0644	edit dl rm
portset.h	3294	0644	edit dl rm
print.h	680	0644	edit dl rm
queue.h	1337	0644	edit dl rm
quota.h	3560	0644	edit dl rm
radix.h	7019	0644	edit dl rm
random.h	1482	0644	edit dl rm
ratelimiter.h	3492	0644	edit dl rm
refcount.h	5103	0644	edit dl rm
regex.h	767	0644	edit dl rm
region.h	2234	0644	edit dl rm
resource.h	2860	0644	edit dl rm
result.h	5580	0644	edit dl rm
resultclass.h	1597	0644	edit dl rm
rwlock.h	2535	0644	edit dl rm
safe.h	1145	0644	edit dl rm
serial.h	1367	0644	edit dl rm
siphash.h	916	0644	edit dl rm
sockaddr.h	6275	0644	edit dl rm
socket.h	24120	0644	edit dl rm
stat.h	803	0644	edit dl rm
stats.h	6689	0644	edit dl rm
stdatomic.h	9116	0644	edit dl rm
stdio.h	1728	0644	edit dl rm
stdtime.h	1392	0644	edit dl rm
strerr.h	575	0644	edit dl rm
string.h	851	0644	edit dl rm
symtab.h	4325	0644	edit dl rm
syslog.h	843	0644	edit dl rm
task.h	17126	0644	edit dl rm
taskpool.h	3281	0644	edit dl rm
thread.h	1908	0644	edit dl rm
time.h	11106	0644	edit dl rm
timer.h	7961	0644	edit dl rm
tm.h	894	0644	edit dl rm
types.h	5854	0644	edit dl rm
url.h	2681	0644	edit dl rm
utf8.h	928	0644	edit dl rm
util.h	14291	0644	edit dl rm
version.h	499	0644	edit dl rm

Edit: /usr/include/bind9/isc/task.h (17126B)

/*
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, you can obtain one at https://mozilla.org/MPL/2.0/.
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
 */

#pragma once

/*****
 ***** Module Info
 *****/

/*! \file isc/task.h
 * \brief 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.
 *
 * \li 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.
 *
 * \li Reliability:
 *	No anticipated impact.
 *
 * \li Resources:
 *	TBS
 *
 * \li Security:
 *	No anticipated impact.
 *
 * \li Standards:
 *	None.
 *
 * \section purge 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.
 */

/***
 *** Imports.
 ***/

#include <stdbool.h>

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

#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)

/*****
 ***** Tasks.
 *****/

ISC_LANG_BEGINDECLS

/***
 *** Types
 ***/

typedef enum {
	isc_taskmgrmode_normal = 0,
	isc_taskmgrmode_privileged
} isc_taskmgrmode_t;

isc_result_t
isc_task_create(isc_taskmgr_t *manager, unsigned int quantum,
		isc_task_t **taskp);
isc_result_t
isc_task_create_bound(isc_taskmgr_t *manager, unsigned int quantum,
		      isc_task_t **taskp, int threadid);
/*%<
 * Create a task, optionally bound to a particular threadid.
 *
 * Notes:
 *
 *\li	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.
 *
 *\li	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:
 *
 *\li	'manager' is a valid task manager.
 *
 *\li	taskp != NULL && *taskp == NULL
 *
 * Ensures:
 *
 *\li	On success, '*taskp' is bound to the new task.
 *
 * Returns:
 *
 *\li   #ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_UNEXPECTED
 *\li	#ISC_R_SHUTTINGDOWN
 */

void
isc_task_ready(isc_task_t *task);
/*%<
 * Enqueue the task onto netmgr queue.
 */

isc_result_t
isc_task_run(isc_task_t *task);
/*%<
 * Run all the queued events for the 'task', returning
 * when the queue is empty or the number of events executed
 * exceeds the 'quantum' specified when the task was created.
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 *
 * Returns:
 *
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_QUOTA
 */

void
isc_task_attach(isc_task_t *source, isc_task_t **targetp);
/*%<
 * Attach *targetp to source.
 *
 * Requires:
 *
 *\li	'source' is a valid task.
 *
 *\li	'targetp' points to a NULL isc_task_t *.
 *
 * Ensures:
 *
 *\li	*targetp is attached to source.
 */

void
isc_task_detach(isc_task_t **taskp);
/*%<
 * Detach *taskp from its task.
 *
 * Requires:
 *
 *\li	'*taskp' is a valid task.
 *
 * Ensures:
 *
 *\li	*taskp is NULL.
 *
 *\li	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.
 *
 *\li	If '*taskp' is the last reference to the task and
 *	the task has been shutdown,
 *		all resources used by the task will be freed.
 */

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

void
isc_task_sendto(isc_task_t *task, isc_event_t **eventp, int c);
/*%<
 * Send '*event' to 'task', if task is idle try starting it on cpu 'c'
 * If 'c' is smaller than 0 then cpu is selected randomly.
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 *\li	eventp != NULL && *eventp != NULL.
 *
 * Ensures:
 *
 *\li	*eventp == NULL.
 */

void
isc_task_sendtoanddetach(isc_task_t **taskp, isc_event_t **eventp, int c);

void
isc_task_sendanddetach(isc_task_t **taskp, isc_event_t **eventp);
/*%<
 * Send '*event' to '*taskp' and then detach '*taskp' from its
 * task. If task is idle try starting it on cpu 'c'
 * If 'c' is smaller than 0 then cpu is selected randomly.
 *
 * Requires:
 *
 *\li	'*taskp' is a valid task.
 *\li	eventp != NULL && *eventp != NULL.
 *
 * Ensures:
 *
 *\li	*eventp == NULL.
 *
 *\li	*taskp == NULL.
 *
 *\li	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.
 *
 *\li	If '*taskp' is the last reference to the task and
 *	the task has been shutdown,
 *		all resources used by the task will be freed.
 */

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:
 *
 *\li	'task' is a valid task.
 *
 *\li	last >= first
 *
 * Ensures:
 *
 *\li	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.
 *
 *\li	A sender of NULL will match any sender.  A NULL tag matches any
 *	tag.
 *
 * Returns:
 *
 *\li	The number of events purged.
 */

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:
 *
 *\li	This function is equivalent to
 *
 *\code
 *		isc_task_purgerange(task, sender, type, type, tag);
 *\endcode
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 *
 * Ensures:
 *
 *\li	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.
 *
 *\li	A sender of NULL will match any sender.  A NULL tag matches any
 *	tag.
 *
 * Returns:
 *
 *\li	The number of events purged.
 */

bool
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:
 *
 *\li	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.
 *
 * \li	Purging never changes the state of the task.
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 *
 * Ensures:
 *
 *\li	'event' is not in the event queue for 'task'.
 *
 * Returns:
 *
 *\li	#true			The event was purged.
 *\li	#false			The event was not in the event queue,
 *					or was marked unpurgeable.
 */

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:
 *
 *\li	'task' is a valid task.
 *
 *\li	last >= first.
 *
 *\li	*events is a valid list.
 *
 * Ensures:
 *
 *\li	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.
 *
 *\li	A sender of NULL will match any sender.  A NULL tag matches any
 *	tag.
 *
 * Returns:
 *
 *\li	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:
 *
 *\li	This function is equivalent to
 *
 *\code
 *		isc_task_unsendrange(task, sender, type, type, tag, events);
 *\endcode
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 *
 *\li	*events is a valid list.
 *
 * Ensures:
 *
 *\li	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:
 *
 *\li	The number of events unsent.
 */

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:
 *
 *\li	Shutdown events are posted in LIFO order.
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 *
 *\li	'action' is a valid task action.
 *
 * Ensures:
 *
 *\li	When the task is shutdown, shutdown events requested with
 *	isc_task_onshutdown() will be appended to the task's event queue.
 *
 *
 * Returns:
 *
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_SHUTTINGDOWN			Task is shutting down.
 */

void
isc_task_shutdown(isc_task_t *task);
/*%<
 * Shutdown 'task'.
 *
 * Notes:
 *
 *\li	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().
 *
 *\li	Trying to shutdown a task that has already been shutdown has no
 *	effect.
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 *
 * Ensures:
 *
 *\li	Any shutdown events requested with isc_task_onshutdown() have been
 *	posted (in LIFO order).
 */

void
isc_task_destroy(isc_task_t **taskp);
/*%<
 * Destroy '*taskp'.
 *
 * Notes:
 *
 *\li	This call is equivalent to:
 *
 *\code
 *		isc_task_shutdown(*taskp);
 *		isc_task_detach(taskp);
 *\endcode
 *
 * Requires:
 *
 *	'*taskp' is a valid task.
 *
 * Ensures:
 *
 *\li	Any shutdown events requested with isc_task_onshutdown() have been
 *	posted (in LIFO order).
 *
 *\li	*taskp == NULL
 *
 *\li	If '*taskp' is the last reference to the task,
 *		all resources used by the task will be freed.
 */

void
isc_task_setname(isc_task_t *task, const char *name, void *tag);
/*%<
 * Name 'task'.
 *
 * Notes:
 *
 *\li	Only the first 15 characters of 'name' will be copied.
 *
 *\li	Naming a task is currently only useful for debugging purposes.
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 */

const char *
isc_task_getname(isc_task_t *task);
/*%<
 * Get the name of 'task', as previously set using isc_task_setname().
 *
 * Notes:
 *\li	This function is for debugging purposes only.
 *
 * Requires:
 *\li	'task' is a valid task.
 *
 * Returns:
 *\li	A non-NULL pointer to a null-terminated string.
 * 	If the task has not been named, the string is
 * 	empty.
 *
 */

isc_nm_t *
isc_task_getnetmgr(isc_task_t *task);

void *
isc_task_gettag(isc_task_t *task);
/*%<
 * Get the tag value for  'task', as previously set using isc_task_settag().
 *
 * Notes:
 *\li	This function is for debugging purposes only.
 *
 * Requires:
 *\li	'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'.
 * It also pauses processing of network events in netmgr if it was provided
 * when taskmgr was created.
 *
 * The exclusive access must be relinquished by calling
 * isc_task_endexclusive() before returning from the current event handler.
 *
 * Requires:
 *\li	'task' is the calling task.
 *
 * Returns:
 *\li	#ISC_R_SUCCESS		The current task now has exclusive access.
 *\li	#ISC_R_LOCKBUSY		Another task has already requested exclusive
 *				access.
 */

void
isc_task_endexclusive(isc_task_t *task);
/*%<
 * Relinquish the exclusive access obtained by isc_task_beginexclusive(),
 * allowing other tasks to execute.
 *
 * Requires:
 *\li	'task' is the calling task, and has obtained
 *		exclusive access by calling isc_task_spl().
 */

void
isc_task_pause(isc_task_t *task0);
void
isc_task_unpause(isc_task_t *task0);
/*%<
 * Pause/unpause this task. Pausing a task removes it from the ready
 * queue if it is present there; this ensures that the task will not
 * run again until unpaused. This is necessary when the libuv network
 * thread executes a function which schedules task manager events; this
 * prevents the task manager from executing the next event in a task
 * before the network thread has finished.
 *
 * Requires:
 *\li	'task' is a valid task, and is not already paused or shutting down.
 */

void
isc_task_getcurrenttime(isc_task_t *task, isc_stdtime_t *t);
void
isc_task_getcurrenttimex(isc_task_t *task, isc_time_t *t);
/*%<
 * Provide the most recent timestamp on the task.  The timestamp is considered
 * as the "current time".
 *
 * isc_task_getcurrentime() returns the time in one-second granularity;
 * isc_task_getcurrentimex() returns it in nanosecond granularity.
 *
 * Requires:
 *\li	'task' is a valid task.
 *\li	't' is a valid non NULL pointer.
 *
 * Ensures:
 *\li	'*t' has the "current time".
 */

bool
isc_task_exiting(isc_task_t *t);
/*%<
 * Returns true if the task is in the process of shutting down,
 * false otherwise.
 *
 * Requires:
 *\li	'task' is a valid task.
 */

void
isc_task_setprivilege(isc_task_t *task, bool 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 resumes running
 * non-privileged tasks.
 *
 * Requires:
 *\li	'task' is a valid task.
 */

bool
isc_task_getprivilege(isc_task_t *task);
/*%<
 * Returns the current value of the task's privilege flag.
 *
 * Requires:
 *\li	'task' is a valid task.
 */

bool
isc_task_privileged(isc_task_t *task);
/*%<
 * Returns true if the task's privilege flag is set *and* the task
 * manager is currently in privileged mode.
 *
 * Requires:
 *\li	'task' is a valid task.
 */

/*****
 ***** Task Manager.
 *****/

void
isc_taskmgr_attach(isc_taskmgr_t *, isc_taskmgr_t **);
void
isc_taskmgr_detach(isc_taskmgr_t **);
/*%<
 * Attach/detach the task manager.
 */

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 operating mode of the task manager. Valid modes are:
 *
 *\li	isc_taskmgrmode_normal
 *\li	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, non-privileged tasks resume running. The task calling
 * this function should be in task-exclusive mode; the privileged tasks
 * will be run after isc_task_endexclusive() is called.
 *
 * Requires:
 *
 *\li	'manager' is a valid task manager.
 */

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:
 *\li	'manager' is a valid task manager.
 *
 *\li	'task' is a valid task.
 */

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:
 *\li	'manager' is a valid task manager.
 *
 *\li	taskp != NULL && *taskp == NULL
 */

#ifdef HAVE_LIBXML2
int
isc_taskmgr_renderxml(isc_taskmgr_t *mgr, void *writer0);
#endif /* ifdef HAVE_LIBXML2 */

#ifdef HAVE_JSON_C
isc_result_t
isc_taskmgr_renderjson(isc_taskmgr_t *mgr, void *tasksobj0);
#endif /* HAVE_JSON_C */

ISC_LANG_ENDDECLS

cmd: