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