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_OBJPOOL_H 13 #define ISC_OBJPOOL_H 1 14 15 /***** 16 ***** Module Info 17 *****/ 18 19 /*! \file isc/pool.h 20 * \brief An object pool is a mechanism for sharing a small pool of 21 * fungible objects among a large number of objects that depend on them. 22 * 23 * This is useful, for example, when it causes performance problems for 24 * large number of zones to share a single memory context or task object, 25 * but it would create a different set of problems for them each to have an 26 * independent task or memory context. 27 */ 28 29 /*** 30 *** Imports. 31 ***/ 32 33 #include <isc/lang.h> 34 #include <isc/mem.h> 35 #include <isc/types.h> 36 37 ISC_LANG_BEGINDECLS 38 39 /***** 40 ***** Types. 41 *****/ 42 43 typedef void (*isc_pooldeallocator_t)(void **object); 44 45 typedef isc_result_t (*isc_poolinitializer_t)(void **target, void *arg); 46 47 typedef struct isc_pool isc_pool_t; 48 49 /***** 50 ***** Functions. 51 *****/ 52 53 isc_result_t 54 isc_pool_create(isc_mem_t *mctx, unsigned int count, isc_pooldeallocator_t free, 55 isc_poolinitializer_t init, void *initarg, isc_pool_t **poolp); 56 /*%< 57 * Create a pool of "count" object pointers. If 'free' is not NULL, 58 * it points to a function that will detach the objects. 'init' 59 * points to a function that will initialize the arguments, and 60 * 'arg' to an argument to be passed into that function (for example, 61 * a relevant manager or context object). 62 * 63 * Requires: 64 * 65 *\li 'mctx' is a valid memory context. 66 * 67 *\li init != NULL 68 * 69 *\li poolp != NULL && *poolp == NULL 70 * 71 * Ensures: 72 * 73 *\li On success, '*poolp' points to the new object pool. 74 * 75 * Returns: 76 * 77 *\li #ISC_R_SUCCESS 78 *\li #ISC_R_NOMEMORY 79 *\li #ISC_R_UNEXPECTED 80 */ 81 82 void * 83 isc_pool_get(isc_pool_t *pool); 84 /*%< 85 * Returns a pointer to an object from the pool. Currently the object 86 * is chosen from the pool at random. (This may be changed in the future 87 * to something that guaratees balance.) 88 */ 89 90 int 91 isc_pool_count(isc_pool_t *pool); 92 /*%< 93 * Returns the number of objcts in the pool 'pool'. 94 */ 95 96 isc_result_t 97 isc_pool_expand(isc_pool_t **sourcep, unsigned int count, isc_pool_t **targetp); 98 99 /*%< 100 * If 'size' is larger than the number of objects in the pool pointed to by 101 * 'sourcep', then a new pool of size 'count' is allocated, the existing 102 * objects are copied into it, additional ones created to bring the 103 * total number up to 'count', and the resulting pool is attached to 104 * 'targetp'. 105 * 106 * If 'count' is less than or equal to the number of objects in 'source', then 107 * 'sourcep' is attached to 'targetp' without any other action being taken. 108 * 109 * In either case, 'sourcep' is detached. 110 * 111 * Requires: 112 * 113 * \li 'sourcep' is not NULL and '*source' is not NULL 114 * \li 'targetp' is not NULL and '*source' is NULL 115 * 116 * Ensures: 117 * 118 * \li On success, '*targetp' points to a valid task pool. 119 * \li On success, '*sourcep' points to NULL. 120 * 121 * Returns: 122 * 123 * \li #ISC_R_SUCCESS 124 * \li #ISC_R_NOMEMORY 125 */ 126 127 void 128 isc_pool_destroy(isc_pool_t **poolp); 129 /*%< 130 * Destroy a task pool. The tasks in the pool are detached but not 131 * shut down. 132 * 133 * Requires: 134 * \li '*poolp' is a valid task pool. 135 */ 136 137 ISC_LANG_ENDDECLS 138 139 #endif /* ISC_OBJPOOL_H */ 140