taskpool.h File Reference

A task pool is a mechanism for sharing a small number of tasks among a large number of objects such that each object is assigned a unique task, but each task may be shared by several objects. More...

#include <isc/lang.h>
#include <isc/task.h>

Go to the source code of this file.

Defines
#define	ISC_TASKPOOL_H   1
Typedefs
typedef typedefISC_LANG_BEGINDECLS struct isc_taskpool	isc_taskpool_t
Functions
isc_result_t	isc_taskpool_create (isc_taskmgr_t *tmgr, isc_mem_t *mctx, unsigned int ntasks, unsigned int quantum, isc_taskpool_t **poolp)
	Create a task pool of "ntasks" tasks, each with quantum "quantum".
void	isc_taskpool_gettask (isc_taskpool_t *pool, isc_task_t **targetp)
	Attach to a task from the pool. Currently the next task is chosen from the pool at random. (This may be changed in the future to something that guaratees balance.).
int	isc_taskpool_size (isc_taskpool_t *pool)
	Returns the number of tasks in the task pool 'pool'.
isc_result_t	isc_taskpool_expand (isc_taskpool_t **sourcep, unsigned int size, isc_taskpool_t **targetp)
	If 'size' is larger than the number of tasks in the pool pointed to by 'sourcep', then a new taskpool of size 'size' is allocated, the existing tasks from are moved into it, additional tasks are created to bring the total number up to 'size', and the resulting pool is attached to 'targetp'.
void	isc_taskpool_destroy (isc_taskpool_t **poolp)
	Destroy a task pool. The tasks in the pool are detached but not shut down.
void	isc_taskpool_setprivilege (isc_taskpool_t *pool, isc_boolean_t priv)
	Set the privilege flag on all tasks in 'pool' to 'priv'. If 'priv' is true, then when the task manager is set into privileged mode, only tasks wihin this pool will be able to execute. (Note: It is important to turn the pool tasks' privilege back off before the last task finishes executing.).

---

Detailed Description

A task pool is a mechanism for sharing a small number of tasks among a large number of objects such that each object is assigned a unique task, but each task may be shared by several objects.

Task pools are used to let objects that can exist in large numbers (e.g., zones) use tasks for synchronization without the memory overhead and unfair scheduling competition that could result from creating a separate task for each object.

Definition in file taskpool.h.

---

Define Documentation

#define ISC_TASKPOOL_H   1

Definition at line 21 of file taskpool.h.

---

Typedef Documentation

typedef typedefISC_LANG_BEGINDECLS struct isc_taskpool isc_taskpool_t

Definition at line 53 of file taskpool.h.

---

Function Documentation

isc_result_t isc_taskpool_create	(	isc_taskmgr_t *	tmgr,
		isc_mem_t *	mctx,
		unsigned int	ntasks,
		unsigned int	quantum,
		isc_taskpool_t **	poolp
	)

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

Requires:

• 'tmgr' is a valid task manager.

• 'mctx' is a valid memory context.

• poolp != NULL && *poolp == NULL

Ensures:

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

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_UNEXPECTED

Definition at line 74 of file taskpool.c.

References alloc_pool(), INSIST, ISC_R_SUCCESS, isc_task_create(), isc_task_setname(), and isc_taskpool_destroy().

Referenced by ATF_TC_BODY(), and dns_zonemgr_setsize().

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

Attach to a task from the pool. Currently the next task is chosen from the pool at random. (This may be changed in the future to something that guaratees balance.).

Definition at line 104 of file taskpool.c.

References isc_random_get(), and isc_task_attach().

Referenced by ATF_TC_BODY(), and dns_zonemgr_managezone().

int isc_taskpool_size

(

isc_taskpool_t *

pool

)

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

Definition at line 111 of file taskpool.c.

References REQUIRE.

Referenced by ATF_TC_BODY().

isc_result_t isc_taskpool_expand	(	isc_taskpool_t **	sourcep,
		unsigned int	size,
		isc_taskpool_t **	targetp
	)

If 'size' is larger than the number of tasks in the pool pointed to by 'sourcep', then a new taskpool of size 'size' is allocated, the existing tasks from are moved into it, additional tasks are created to bring the total number up to 'size', and the resulting pool is attached to 'targetp'.

If 'size' is less than or equal to the tasks in pool 'source', then 'sourcep' is attached to 'targetp' without any other action being taken.

In either case, 'sourcep' is detached.

Requires:

• 'sourcep' is not NULL and '*source' is not NULL
• 'targetp' is not NULL and '*source' is NULL

Ensures:

• On success, '*targetp' points to a valid task pool.
• On success, '*sourcep' points to NULL.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY

Definition at line 117 of file taskpool.c.

References alloc_pool(), ISC_R_SUCCESS, isc_task_create(), isc_task_setname(), isc_taskpool_destroy(), and REQUIRE.

Referenced by ATF_TC_BODY(), and dns_zonemgr_setsize().

void isc_taskpool_destroy

(

isc_taskpool_t **

poolp

)

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

Requires:

• '*poolp' is a valid task pool.

Definition at line 164 of file taskpool.c.

References isc_mem_put, isc_mem_putanddetach, and isc_task_detach().

Referenced by ATF_TC_BODY(), dns_zonemgr_shutdown(), isc_taskpool_create(), and isc_taskpool_expand().

void isc_taskpool_setprivilege	(	isc_taskpool_t *	pool,
		isc_boolean_t	priv
	)

Set the privilege flag on all tasks in 'pool' to 'priv'. If 'priv' is true, then when the task manager is set into privileged mode, only tasks wihin this pool will be able to execute. (Note: It is important to turn the pool tasks' privilege back off before the last task finishes executing.).

Requires:

• 'pool' is a valid task pool.

Definition at line 178 of file taskpool.c.

References isc_task_setprivilege(), and REQUIRE.

Referenced by ATF_TC_BODY(), and dns_zonemgr_setsize().

---