/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef ISC_TASKPOOL_H

[12] Fix | Delete

#define ISC_TASKPOOL_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file isc/taskpool.h

[19] Fix | Delete

* \brief A task pool is a mechanism for sharing a small number of tasks

[20] Fix | Delete

* among a large number of objects such that each object is

[21] Fix | Delete

* assigned a unique task, but each task may be shared by several

[22] Fix | Delete

* objects.

[23] Fix | Delete

*

[24] Fix | Delete

* Task pools are used to let objects that can exist in large

[25] Fix | Delete

* numbers (e.g., zones) use tasks for synchronization without

[26] Fix | Delete

* the memory overhead and unfair scheduling competition that

[27] Fix | Delete

* could result from creating a separate task for each object.

[28] Fix | Delete

*/

[29] Fix | Delete

[30] Fix | Delete

[31] Fix | Delete

/***

[32] Fix | Delete

*** Imports.

[33] Fix | Delete

***/

[34] Fix | Delete

[35] Fix | Delete

#include <stdbool.h>

[36] Fix | Delete

[37] Fix | Delete

#include <isc/lang.h>

[38] Fix | Delete

#include <isc/task.h>

[39] Fix | Delete

[40] Fix | Delete

ISC_LANG_BEGINDECLS

[41] Fix | Delete

[42] Fix | Delete

/*****

[43] Fix | Delete

***** Types.

[44] Fix | Delete

*****/

[45] Fix | Delete

[46] Fix | Delete

typedef struct isc_taskpool isc_taskpool_t;

[47] Fix | Delete

[48] Fix | Delete

/*****

[49] Fix | Delete

***** Functions.

[50] Fix | Delete

*****/

[51] Fix | Delete

[52] Fix | Delete

isc_result_t

[53] Fix | Delete

isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx,

[54] Fix | Delete

unsigned int ntasks, unsigned int quantum,

[55] Fix | Delete

isc_taskpool_t **poolp);

[56] Fix | Delete

/*%<

[57] Fix | Delete

* Create a task pool of "ntasks" tasks, each with quantum

[58] Fix | Delete

* "quantum".

[59] Fix | Delete

*

[60] Fix | Delete

* Requires:

[61] Fix | Delete

*

[62] Fix | Delete

*\li 'tmgr' is a valid task manager.

[63] Fix | Delete

*

[64] Fix | Delete

*\li 'mctx' is a valid memory context.

[65] Fix | Delete

*

[66] Fix | Delete

*\li poolp != NULL && *poolp == NULL

[67] Fix | Delete

*

[68] Fix | Delete

* Ensures:

[69] Fix | Delete

*

[70] Fix | Delete

*\li On success, '*taskp' points to the new task pool.

[71] Fix | Delete

*

[72] Fix | Delete

* Returns:

[73] Fix | Delete

*

[74] Fix | Delete

*\li #ISC_R_SUCCESS

[75] Fix | Delete

*\li #ISC_R_NOMEMORY

[76] Fix | Delete

*\li #ISC_R_UNEXPECTED

[77] Fix | Delete

*/

[78] Fix | Delete

[79] Fix | Delete

void

[80] Fix | Delete

isc_taskpool_gettask(isc_taskpool_t *pool, isc_task_t **targetp);

[81] Fix | Delete

/*%<

[82] Fix | Delete

* Attach to a task from the pool. Currently the next task is chosen

[83] Fix | Delete

* from the pool at random. (This may be changed in the future to

[84] Fix | Delete

* something that guaratees balance.)

[85] Fix | Delete

*/

[86] Fix | Delete

[87] Fix | Delete

int

[88] Fix | Delete

isc_taskpool_size(isc_taskpool_t *pool);

[89] Fix | Delete

/*%<

[90] Fix | Delete

* Returns the number of tasks in the task pool 'pool'.

[91] Fix | Delete

*/

[92] Fix | Delete

[93] Fix | Delete

isc_result_t

[94] Fix | Delete

isc_taskpool_expand(isc_taskpool_t **sourcep, unsigned int size,

[95] Fix | Delete

isc_taskpool_t **targetp);

[96] Fix | Delete

[97] Fix | Delete

/*%<

[98] Fix | Delete

* If 'size' is larger than the number of tasks in the pool pointed to by

[99] Fix | Delete

* 'sourcep', then a new taskpool of size 'size' is allocated, the existing

[100] Fix | Delete

* tasks from are moved into it, additional tasks are created to bring the

[101] Fix | Delete

* total number up to 'size', and the resulting pool is attached to

[102] Fix | Delete

* 'targetp'.

[103] Fix | Delete

*

[104] Fix | Delete

* If 'size' is less than or equal to the tasks in pool 'source', then

[105] Fix | Delete

* 'sourcep' is attached to 'targetp' without any other action being taken.

[106] Fix | Delete

*

[107] Fix | Delete

* In either case, 'sourcep' is detached.

[108] Fix | Delete

*

[109] Fix | Delete

* Requires:

[110] Fix | Delete

*

[111] Fix | Delete

* \li 'sourcep' is not NULL and '*source' is not NULL

[112] Fix | Delete

* \li 'targetp' is not NULL and '*source' is NULL

[113] Fix | Delete

*

[114] Fix | Delete

* Ensures:

[115] Fix | Delete

*

[116] Fix | Delete

* \li On success, '*targetp' points to a valid task pool.

[117] Fix | Delete

* \li On success, '*sourcep' points to NULL.

[118] Fix | Delete

*

[119] Fix | Delete

* Returns:

[120] Fix | Delete

*

[121] Fix | Delete

* \li #ISC_R_SUCCESS

[122] Fix | Delete

* \li #ISC_R_NOMEMORY

[123] Fix | Delete

*/

[124] Fix | Delete

[125] Fix | Delete

void

[126] Fix | Delete

isc_taskpool_destroy(isc_taskpool_t **poolp);

[127] Fix | Delete

/*%<

[128] Fix | Delete

* Destroy a task pool. The tasks in the pool are detached but not

[129] Fix | Delete

* shut down.

[130] Fix | Delete

*

[131] Fix | Delete

* Requires:

[132] Fix | Delete

* \li '*poolp' is a valid task pool.

[133] Fix | Delete

*/

[134] Fix | Delete

[135] Fix | Delete

void

[136] Fix | Delete

isc_taskpool_setprivilege(isc_taskpool_t *pool, bool priv);

[137] Fix | Delete

/*%<

[138] Fix | Delete

* Set the privilege flag on all tasks in 'pool' to 'priv'. If 'priv' is

[139] Fix | Delete

* true, then when the task manager is set into privileged mode, only

[140] Fix | Delete

* tasks wihin this pool will be able to execute. (Note: It is important

[141] Fix | Delete

* to turn the pool tasks' privilege back off before the last task finishes

[142] Fix | Delete

* executing.)

[143] Fix | Delete

*

[144] Fix | Delete

* Requires:

[145] Fix | Delete

* \li 'pool' is a valid task pool.

[146] Fix | Delete

*/

[147] Fix | Delete

[148] Fix | Delete

ISC_LANG_ENDDECLS

[149] Fix | Delete

[150] Fix | Delete

#endif /* ISC_TASKPOOL_H */

[151] Fix | Delete

[152] Fix | Delete