1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 7 * 8 * See the COPYRIGHT file distributed with this work for additional 9 * information regarding copyright ownership. 10 */ 11 12 #ifndef ISC_TASKPOOL_H 13 #define ISC_TASKPOOL_H 1 14 15 /***** 16 ***** Module Info 17 *****/ 18 19 /*! \file isc/taskpool.h 20 * \brief A task pool is a mechanism for sharing a small number of tasks 21 * among a large number of objects such that each object is 22 * assigned a unique task, but each task may be shared by several 23 * objects. 24 * 25 * Task pools are used to let objects that can exist in large 26 * numbers (e.g., zones) use tasks for synchronization without 27 * the memory overhead and unfair scheduling competition that 28 * could result from creating a separate task for each object. 29 */ 30 31 /*** 32 *** Imports. 33 ***/ 34 35 #include <stdbool.h> 36 37 #include <isc/lang.h> 38 #include <isc/task.h> 39 40 ISC_LANG_BEGINDECLS 41 42 /***** 43 ***** Types. 44 *****/ 45 46 typedef struct isc_taskpool isc_taskpool_t; 47 48 /***** 49 ***** Functions. 50 *****/ 51 52 isc_result_t 53 isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx, unsigned int ntasks, 54 unsigned int quantum, bool priv, isc_taskpool_t **poolp); 55 /*%< 56 * Create a task pool of "ntasks" tasks, each with quantum 57 * "quantum". 58 * 59 * Requires: 60 * 61 *\li 'tmgr' is a valid task manager. 62 * 63 *\li 'mctx' is a valid memory context. 64 * 65 *\li poolp != NULL && *poolp == NULL 66 * 67 * Ensures: 68 * 69 *\li On success, '*taskp' points to the new task pool. 70 * 71 * Returns: 72 * 73 *\li #ISC_R_SUCCESS 74 *\li #ISC_R_NOMEMORY 75 *\li #ISC_R_UNEXPECTED 76 */ 77 78 void 79 isc_taskpool_gettask(isc_taskpool_t *pool, isc_task_t **targetp); 80 /*%< 81 * Attach to a task from the pool. Currently the next task is chosen 82 * from the pool at random. (This may be changed in the future to 83 * something that guaratees balance.) 84 */ 85 86 int 87 isc_taskpool_size(isc_taskpool_t *pool); 88 /*%< 89 * Returns the number of tasks in the task pool 'pool'. 90 */ 91 92 isc_result_t 93 isc_taskpool_expand(isc_taskpool_t **sourcep, unsigned int size, bool priv, 94 isc_taskpool_t **targetp); 95 96 /*%< 97 * If 'size' is larger than the number of tasks in the pool pointed to by 98 * 'sourcep', then a new taskpool of size 'size' is allocated, the existing 99 * tasks from are moved into it, additional tasks are created to bring the 100 * total number up to 'size', and the resulting pool is attached to 101 * 'targetp'. 102 * 103 * If 'size' is less than or equal to the tasks in pool 'source', then 104 * 'sourcep' is attached to 'targetp' without any other action being taken. 105 * 106 * In either case, 'sourcep' is detached. 107 * 108 * Requires: 109 * 110 * \li 'sourcep' is not NULL and '*source' is not NULL 111 * \li 'targetp' is not NULL and '*source' is NULL 112 * 113 * Ensures: 114 * 115 * \li On success, '*targetp' points to a valid task pool. 116 * \li On success, '*sourcep' points to NULL. 117 * 118 * Returns: 119 * 120 * \li #ISC_R_SUCCESS 121 * \li #ISC_R_NOMEMORY 122 */ 123 124 void 125 isc_taskpool_destroy(isc_taskpool_t **poolp); 126 /*%< 127 * Destroy a task pool. The tasks in the pool are detached but not 128 * shut down. 129 * 130 * Requires: 131 * \li '*poolp' is a valid task pool. 132 */ 133 134 ISC_LANG_ENDDECLS 135 136 #endif /* ISC_TASKPOOL_H */ 137