<commit_before>/*
 * Copyright (C) 1998, 1999, 2000  Internet Software Consortium.
 * 
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
 * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
 * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
 * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
 * SOFTWARE.
 */

#ifndef ISC_TASK_H
#define ISC_TASK_H 1

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

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


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

#include <isc/lang.h>
#include <isc/types.h>
#include <isc/eventclass.h>
#include <isc/mem.h>
#include <isc/result.h>

ISC_LANG_BEGINDECLS

#define ISC_TASKEVENT_FIRSTEVENT	(ISC_EVENTCLASS_TASK + 0)
#define ISC_TASKEVENT_SHUTDOWN		(ISC_EVENTCLASS_TASK + 1)
#define ISC_TASKEVENT_LASTEVENT		(ISC_EVENTCLASS_TASK + 65535)

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

isc_result_t
isc_task_create(isc_taskmgr_t *manager, isc_mem_t *mctx,
		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.
 *
 *	'mctx' is a valid memory context.
 *
 *	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
 */

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

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

isc_mem_t *
isc_task_mem(isc_task_t *task);
/*
 * Get the task's memory context.
 *
 * Requires:
 *
 *	'task' is a valid task.
 *
 * Returns:
 *
 *	The memory context specified when the task was created.
 */

void
isc_task_send(isc_task_t *task, isc_event_t **eventp);
/*
 * Send '*event' to 'task'.
 *
 * Requires:
 *
 *	'task' is a valid task.
 *
 * Ensures
 *
 *	On success, *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:
 *
 *	'*taskp' is a valid task.
 *
 * 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.
 */

/*
 * 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 cancelling a timer.<commit_msg>clarified requires/ensures for isc_task_detach and isc_task_sendanddetach<commit_after>/*
 * Copyright (C) 1998, 1999, 2000  Internet Software Consortium.
 * 
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
 * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
 * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
 * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
 * SOFTWARE.
 */

#ifndef ISC_TASK_H
#define ISC_TASK_H 1

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

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


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

#include <isc/lang.h>
#include <isc/types.h>
#include <isc/eventclass.h>
#include <isc/mem.h>
#include <isc/result.h>

ISC_LANG_BEGINDECLS

#define ISC_TASKEVENT_FIRSTEVENT	(ISC_EVENTCLASS_TASK + 0)
#define ISC_TASKEVENT_SHUTDOWN		(ISC_EVENTCLASS_TASK + 1)
#define ISC_TASKEVENT_LASTEVENT		(ISC_EVENTCLASS_TASK + 65535)

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

isc_result_t
isc_task_create(isc_taskmgr_t *manager, isc_mem_t *mctx,
		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.
 *
 *	'mctx' is a valid memory context.
 *
 *	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
 */

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

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

isc_mem_t *
isc_task_mem(isc_task_t *task);
/*
 * Get the task's memory context.
 *
 * Requires:
 *
 *	'task' is a valid task.
 *
 * Returns:
 *
 *	The memory context specified when the task was created.
 */

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

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

/*
 * 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 cancelling a timer.
{'fraction_non_alphanumeric': 0.10016048333805343, 'fraction_numerical': 0.0037760785424336826, 'mean_word_length': 3.5351027397260273, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7119114', 'n_tokens_mistral': 3690, 'n_tokens_neox': 3487, 'n_words': 1356}