/*
* 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
Mr. DellatioNx196 GaLers xh3LL Backd00r 1.0, Coded By Mr. DellatioNx196 - Bogor BlackHat