#$@%#$%!

Ngiler SH3LL 360
: / proc / thread-self / root / usr / include / bind9 / isc /

Information Server
MySQL : OFF Perl : OFF CURL : ON WGET : OFF PKEXEC : OFF

Directive	Local Value
IP Address	162.0.209.101
System	Linux premium169.web-hosting.com 4.18.0-553.50.1.lve.el8.x86_64 #1 SMP Thu Apr 17 19:10:24 UTC 2025 x86_64
User	luxeelil
PHP Version	8.0.30
Software	LiteSpeed
Doc root	Writable

Edit File : task.h \| Size : 21.04 KB
/* * 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. / #ifndef ISC_TASK_H #define ISC_TASK_H 1 /** * 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/json.h> #include <isc/lang.h> #include <isc/stdtime.h> #include <isc/types.h> #include <isc/xml.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_taskqueue_normal = 0, isc_taskqueue_slow = 1, } isc_taskqueue_t; #define ISC_TASK_QUANTUM_SLOW 1024 typedef enum { isc_taskmgrmode_normal = 0, isc_taskmgrmode_privileged } isc_taskmgrmode_t; /% Task and task manager methods / typedef struct isc_taskmgrmethods { void (destroy)(isc_taskmgr_t *managerp); void (setmode)(isc_taskmgr_t manager, isc_taskmgrmode_t mode); isc_taskmgrmode_t (mode)(isc_taskmgr_t manager); isc_result_t (taskcreate)(isc_taskmgr_t manager, unsigned int quantum, isc_task_t taskp); void (setexcltask)(isc_taskmgr_t mgr, isc_task_t task); isc_result_t (excltask)(isc_taskmgr_t mgr, isc_task_t *taskp); } isc_taskmgrmethods_t; typedef struct isc_taskmethods { void (attach)(isc_task_t source, isc_task_t targetp); void (detach)(isc_task_t *taskp); void (destroy)(isc_task_t *taskp); void (send)(isc_task_t task, isc_event_t eventp); void (sendanddetach)(isc_task_t taskp, isc_event_t eventp); unsigned int (unsend)(isc_task_t task, void sender, isc_eventtype_t type, void tag, isc_eventlist_t events); isc_result_t (onshutdown)(isc_task_t task, isc_taskaction_t action, void arg); void (shutdown)(isc_task_t task); void (setname)(isc_task_t task, const char name, void tag); unsigned int (purgeevents)(isc_task_t task, void sender, isc_eventtype_t type, void tag); unsigned int (purgerange)(isc_task_t task, void sender, isc_eventtype_t first, isc_eventtype_t last, void tag); isc_result_t (beginexclusive)(isc_task_t task); void (endexclusive)(isc_task_t task); void (setprivilege)(isc_task_t task, bool priv); bool (privilege)(isc_task_t task); } isc_taskmethods_t; /% This structure is actually just the common prefix of a task manager * object implementation's version of an isc_taskmgr_t. * \brief * Direct use of this structure by clients is forbidden. task implementations * may change the structure. 'magic' must be ISCAPI_TASKMGR_MAGIC for any * of the isc_task_ routines to work. task implementations must maintain * all task invariants. / struct isc_taskmgr { unsigned int impmagic; unsigned int magic; isc_taskmgrmethods_t methods; }; #define ISCAPI_TASKMGR_MAGIC ISC_MAGIC('A','t','m','g') #define ISCAPI_TASKMGR_VALID(m) ((m) != NULL && \ (m)->magic == ISCAPI_TASKMGR_MAGIC) /% This is the common prefix of a task object. The same note as * that for the taskmgr structure applies. / struct isc_task { unsigned int impmagic; unsigned int magic; isc_taskmethods_t methods; }; #define ISCAPI_TASK_MAGIC ISC_MAGIC('A','t','s','t') #define ISCAPI_TASK_VALID(s) ((s) != NULL && \ (s)->magic == ISCAPI_TASK_MAGIC) isc_result_t isc_task_create(isc_taskmgr_t manager, unsigned int quantum, isc_task_t taskp); /%< * Create a task. * * 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_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); /%< * Send 'event' to 'task'. * Requires: * \li 'task' is a valid task. \li eventp != NULL && eventp != NULL. * Ensures: * \li eventp == NULL. / void isc_task_sendanddetach(isc_task_t taskp, isc_event_t eventp); /%< * Send 'event' to 'taskp' and then detach 'taskp' from its task. * * 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. * / 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'. * * 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_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 will automatically * return to normal execution mode and nonprivileged task can resume. * * Requires: \li 'task' is a valid task. / bool isc_task_privilege(isc_task_t task); /%< * Returns the current value of the task's privilege flag. * * Requires: \li 'task' is a valid task. / /*** * Task Manager. **/ 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. * * Notes: * \li '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. * \li 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: * \li 'mctx' is a valid memory context. \li workers > 0 \li managerp != NULL && managerp == NULL * \li 'actx' is a valid application context (for createinctx()). * Ensures: * \li On success, 'managerp' will be attached to the newly created task * manager. * * Returns: * \li #ISC_R_SUCCESS \li #ISC_R_NOMEMORY \li #ISC_R_NOTHREADS No threads could be created. \li #ISC_R_UNEXPECTED An unexpected error occurred. \li #ISC_R_SHUTTINGDOWN The non-threaded, shared, task manager shutting down. / 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: * \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, 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: * \li 'manager' is a valid task manager. / void isc_taskmgr_destroy(isc_taskmgr_t *managerp); /%< * Destroy 'managerp'. * Notes: * \li 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. * \li 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(). * \li 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: * \li 'managerp' is a valid task manager. * \li isc_taskmgr_destroy() has not be called previously on 'managerp'. * * Ensures: * \li All resources used by the task manager, and any tasks it managed, have been freed. / 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, xmlTextWriterPtr writer); #endif #ifdef HAVE_JSON isc_result_t isc_taskmgr_renderjson(isc_taskmgr_t mgr, json_object tasksobj); #endif /%< * See isc_taskmgr_create() above. / typedef isc_result_t (isc_taskmgrcreatefunc_t)(isc_mem_t mctx, unsigned int workers, unsigned int default_quantum, isc_taskmgr_t managerp); 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. / ISC_LANG_ENDDECLS #endif / ISC_TASK_H */ Back

Edit File : task.h | Size : 21.04 KB

/*
 * 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.
 */

#ifndef ISC_TASK_H
#define ISC_TASK_H 1

/*****
 ***** 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/json.h>
#include <isc/lang.h>
#include <isc/stdtime.h>
#include <isc/types.h>
#include <isc/xml.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_taskqueue_normal = 0,
	isc_taskqueue_slow = 1,
} isc_taskqueue_t;

#define ISC_TASK_QUANTUM_SLOW 1024

typedef enum {
	isc_taskmgrmode_normal = 0,
	isc_taskmgrmode_privileged
} isc_taskmgrmode_t;

/*% Task and task manager methods */
typedef struct isc_taskmgrmethods {
	void		(*destroy)(isc_taskmgr_t **managerp);
	void		(*setmode)(isc_taskmgr_t *manager,
				   isc_taskmgrmode_t mode);
	isc_taskmgrmode_t (*mode)(isc_taskmgr_t *manager);
	isc_result_t	(*taskcreate)(isc_taskmgr_t *manager,
				      unsigned int quantum,
				      isc_task_t **taskp);
	void (*setexcltask)(isc_taskmgr_t *mgr, isc_task_t *task);
	isc_result_t (*excltask)(isc_taskmgr_t *mgr, isc_task_t **taskp);
} isc_taskmgrmethods_t;

typedef struct isc_taskmethods {
	void (*attach)(isc_task_t *source, isc_task_t **targetp);
	void (*detach)(isc_task_t **taskp);
	void (*destroy)(isc_task_t **taskp);
	void (*send)(isc_task_t *task, isc_event_t **eventp);
	void (*sendanddetach)(isc_task_t **taskp, isc_event_t **eventp);
	unsigned int (*unsend)(isc_task_t *task, void *sender, isc_eventtype_t type,
			       void *tag, isc_eventlist_t *events);
	isc_result_t (*onshutdown)(isc_task_t *task, isc_taskaction_t action,
				   void *arg);
	void (*shutdown)(isc_task_t *task);
	void (*setname)(isc_task_t *task, const char *name, void *tag);
	unsigned int (*purgeevents)(isc_task_t *task, void *sender,
				    isc_eventtype_t type, void *tag);
	unsigned int (*purgerange)(isc_task_t *task, void *sender,
				   isc_eventtype_t first, isc_eventtype_t last,
				   void *tag);
	isc_result_t (*beginexclusive)(isc_task_t *task);
	void (*endexclusive)(isc_task_t *task);
    void (*setprivilege)(isc_task_t *task, bool priv);
    bool (*privilege)(isc_task_t *task);
} isc_taskmethods_t;

/*%
 * This structure is actually just the common prefix of a task manager
 * object implementation's version of an isc_taskmgr_t.
 * \brief
 * Direct use of this structure by clients is forbidden.  task implementations
 * may change the structure.  'magic' must be ISCAPI_TASKMGR_MAGIC for any
 * of the isc_task_ routines to work.  task implementations must maintain
 * all task invariants.
 */
struct isc_taskmgr {
	unsigned int		impmagic;
	unsigned int		magic;
	isc_taskmgrmethods_t	*methods;
};

#define ISCAPI_TASKMGR_MAGIC	ISC_MAGIC('A','t','m','g')
#define ISCAPI_TASKMGR_VALID(m)	((m) != NULL && \
				 (m)->magic == ISCAPI_TASKMGR_MAGIC)

/*%
 * This is the common prefix of a task object.  The same note as
 * that for the taskmgr structure applies.
 */
struct isc_task {
	unsigned int		impmagic;
	unsigned int		magic;
	isc_taskmethods_t	*methods;
};

#define ISCAPI_TASK_MAGIC	ISC_MAGIC('A','t','s','t')
#define ISCAPI_TASK_VALID(s)	((s) != NULL && \
				 (s)->magic == ISCAPI_TASK_MAGIC)

isc_result_t
isc_task_create(isc_taskmgr_t *manager, unsigned int quantum,
		isc_task_t **taskp);
/*%<
 * Create a task.
 *
 * 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_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);
/*%<
 * Send '*event' to 'task'.
 *
 * Requires:
 *
 *\li	'task' is a valid task.
 *\li	eventp != NULL && *eventp != NULL.
 *
 * Ensures:
 *
 *\li	*eventp == NULL.
 */

void
isc_task_sendanddetach(isc_task_t **taskp, isc_event_t **eventp);
/*%<
 * Send '*event' to '*taskp' and then detach '*taskp' from its
 * task.
 *
 * 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.
 *
 */

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'.
 *
 * 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_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 will automatically
 * return to normal execution mode and nonprivileged task can resume.
 *
 * Requires:
 *\li	'task' is a valid task.
 */

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

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

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.
 *
 * Notes:
 *
 *\li	'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.
 *
 *\li	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:
 *
 *\li      'mctx' is a valid memory context.
 *
 *\li	workers > 0
 *
 *\li	managerp != NULL && *managerp == NULL
 *
 *\li	'actx' is a valid application context (for createinctx()).
 *
 * Ensures:
 *
 *\li	On success, '*managerp' will be attached to the newly created task
 *	manager.
 *
 * Returns:
 *
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_NOTHREADS		No threads could be created.
 *\li	#ISC_R_UNEXPECTED		An unexpected error occurred.
 *\li	#ISC_R_SHUTTINGDOWN      	The non-threaded, shared, task
 *					manager shutting down.
 */

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

void
isc_taskmgr_destroy(isc_taskmgr_t **managerp);
/*%<
 * Destroy '*managerp'.
 *
 * Notes:
 *
 *\li	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.
 *
 *\li	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().
 *
 *\li	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:
 *
 *\li	'*managerp' is a valid task manager.
 *
 *\li	isc_taskmgr_destroy() has not be called previously on '*managerp'.
 *
 * Ensures:
 *
 *\li	All resources used by the task manager, and any tasks it managed,
 *	have been freed.
 */

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, xmlTextWriterPtr writer);
#endif

#ifdef HAVE_JSON
isc_result_t
isc_taskmgr_renderjson(isc_taskmgr_t *mgr, json_object *tasksobj);
#endif

/*%<
 * See isc_taskmgr_create() above.
 */
typedef isc_result_t
(*isc_taskmgrcreatefunc_t)(isc_mem_t *mctx, unsigned int workers,
			   unsigned int default_quantum,
			   isc_taskmgr_t **managerp);

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.
 */

ISC_LANG_ENDDECLS

#endif /* ISC_TASK_H */

Back