1/* 2 * Copyright (C) 2004-2007, 2011, 2012 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 1999-2001 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and/or distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 * PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18/* $Id$ */ 19 20#ifndef ISC_TASKPOOL_H 21#define ISC_TASKPOOL_H 1 22 23/***** 24 ***** Module Info 25 *****/ 26 27/*! \file isc/taskpool.h 28 * \brief A task pool is a mechanism for sharing a small number of tasks 29 * among a large number of objects such that each object is 30 * assigned a unique task, but each task may be shared by several 31 * objects. 32 * 33 * Task pools are used to let objects that can exist in large 34 * numbers (e.g., zones) use tasks for synchronization without 35 * the memory overhead and unfair scheduling competition that 36 * could result from creating a separate task for each object. 37 */ 38 39 40/*** 41 *** Imports. 42 ***/ 43 44#include <isc/lang.h> 45#include <isc/task.h> 46 47ISC_LANG_BEGINDECLS 48 49/***** 50 ***** Types. 51 *****/ 52 53typedef struct isc_taskpool isc_taskpool_t; 54 55/***** 56 ***** Functions. 57 *****/ 58 59isc_result_t 60isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx, 61 unsigned int ntasks, unsigned int quantum, 62 isc_taskpool_t **poolp); 63/*%< 64 * Create a task pool of "ntasks" tasks, each with quantum 65 * "quantum". 66 * 67 * Requires: 68 * 69 *\li 'tmgr' is a valid task manager. 70 * 71 *\li 'mctx' is a valid memory context. 72 * 73 *\li poolp != NULL && *poolp == NULL 74 * 75 * Ensures: 76 * 77 *\li On success, '*taskp' points to the new task pool. 78 * 79 * Returns: 80 * 81 *\li #ISC_R_SUCCESS 82 *\li #ISC_R_NOMEMORY 83 *\li #ISC_R_UNEXPECTED 84 */ 85 86void 87isc_taskpool_gettask(isc_taskpool_t *pool, isc_task_t **targetp); 88/*%< 89 * Attach to a task from the pool. Currently the next task is chosen 90 * from the pool at random. (This may be changed in the future to 91 * something that guaratees balance.) 92 */ 93 94int 95isc_taskpool_size(isc_taskpool_t *pool); 96/*%< 97 * Returns the number of tasks in the task pool 'pool'. 98 */ 99 100isc_result_t 101isc_taskpool_expand(isc_taskpool_t **sourcep, unsigned int size, 102 isc_taskpool_t **targetp); 103 104/*%< 105 * If 'size' is larger than the number of tasks in the pool pointed to by 106 * 'sourcep', then a new taskpool of size 'size' is allocated, the existing 107 * tasks from are moved into it, additional tasks are created to bring the 108 * total number up to 'size', and the resulting pool is attached to 109 * 'targetp'. 110 * 111 * If 'size' is less than or equal to the tasks in pool 'source', then 112 * 'sourcep' is attached to 'targetp' without any other action being taken. 113 * 114 * In either case, 'sourcep' is detached. 115 * 116 * Requires: 117 * 118 * \li 'sourcep' is not NULL and '*source' is not NULL 119 * \li 'targetp' is not NULL and '*source' is NULL 120 * 121 * Ensures: 122 * 123 * \li On success, '*targetp' points to a valid task pool. 124 * \li On success, '*sourcep' points to NULL. 125 * 126 * Returns: 127 * 128 * \li #ISC_R_SUCCESS 129 * \li #ISC_R_NOMEMORY 130 */ 131 132void 133isc_taskpool_destroy(isc_taskpool_t **poolp); 134/*%< 135 * Destroy a task pool. The tasks in the pool are detached but not 136 * shut down. 137 * 138 * Requires: 139 * \li '*poolp' is a valid task pool. 140 */ 141 142void 143isc_taskpool_setprivilege(isc_taskpool_t *pool, isc_boolean_t priv); 144/*%< 145 * Set the privilege flag on all tasks in 'pool' to 'priv'. If 'priv' is 146 * true, then when the task manager is set into privileged mode, only 147 * tasks wihin this pool will be able to execute. (Note: It is important 148 * to turn the pool tasks' privilege back off before the last task finishes 149 * executing.) 150 * 151 * Requires: 152 * \li 'pool' is a valid task pool. 153 */ 154 155ISC_LANG_ENDDECLS 156 157#endif /* ISC_TASKPOOL_H */ 158