1 /* $NetBSD: pool.h,v 1.1.1.3 2014/12/10 03:34:44 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC") 5 * 6 * Permission to use, copy, modify, and/or distribute this software for any 7 * purpose with or without fee is hereby granted, provided that the above 8 * copyright notice and this permission notice appear in all copies. 9 * 10 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 11 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 12 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 13 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 14 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 15 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 16 * PERFORMANCE OF THIS SOFTWARE. 17 */ 18 19 #ifndef ISC_OBJPOOL_H 20 #define ISC_OBJPOOL_H 1 21 22 /***** 23 ***** Module Info 24 *****/ 25 26 /*! \file isc/pool.h 27 * \brief An object pool is a mechanism for sharing a small pool of 28 * fungible objects among a large number of objects that depend on them. 29 * 30 * This is useful, for example, when it causes performance problems for 31 * large number of zones to share a single memory context or task object, 32 * but it would create a different set of problems for them each to have an 33 * independent task or memory context. 34 */ 35 36 37 /*** 38 *** Imports. 39 ***/ 40 41 #include <isc/lang.h> 42 #include <isc/mem.h> 43 #include <isc/types.h> 44 45 ISC_LANG_BEGINDECLS 46 47 /***** 48 ***** Types. 49 *****/ 50 51 typedef void 52 (*isc_pooldeallocator_t)(void **object); 53 54 typedef isc_result_t 55 (*isc_poolinitializer_t)(void **target, void *arg); 56 57 typedef struct isc_pool isc_pool_t; 58 59 /***** 60 ***** Functions. 61 *****/ 62 63 isc_result_t 64 isc_pool_create(isc_mem_t *mctx, unsigned int count, 65 isc_pooldeallocator_t free, 66 isc_poolinitializer_t init, void *initarg, 67 isc_pool_t **poolp); 68 /*%< 69 * Create a pool of "count" object pointers. If 'free' is not NULL, 70 * it points to a function that will detach the objects. 'init' 71 * points to a function that will initialize the arguments, and 72 * 'arg' to an argument to be passed into that function (for example, 73 * a relevant manager or context object). 74 * 75 * Requires: 76 * 77 *\li 'mctx' is a valid memory context. 78 * 79 *\li init != NULL 80 * 81 *\li poolp != NULL && *poolp == NULL 82 * 83 * Ensures: 84 * 85 *\li On success, '*poolp' points to the new object pool. 86 * 87 * Returns: 88 * 89 *\li #ISC_R_SUCCESS 90 *\li #ISC_R_NOMEMORY 91 *\li #ISC_R_UNEXPECTED 92 */ 93 94 void * 95 isc_pool_get(isc_pool_t *pool); 96 /*%< 97 * Returns a pointer to an object from the pool. Currently the object 98 * is chosen from the pool at random. (This may be changed in the future 99 * to something that guaratees balance.) 100 */ 101 102 int 103 isc_pool_count(isc_pool_t *pool); 104 /*%< 105 * Returns the number of objcts in the pool 'pool'. 106 */ 107 108 isc_result_t 109 isc_pool_expand(isc_pool_t **sourcep, unsigned int count, isc_pool_t **targetp); 110 111 /*%< 112 * If 'size' is larger than the number of objects in the pool pointed to by 113 * 'sourcep', then a new pool of size 'count' is allocated, the existing 114 * objects are copied into it, additional ones created to bring the 115 * total number up to 'count', and the resulting pool is attached to 116 * 'targetp'. 117 * 118 * If 'count' is less than or equal to the number of objects in 'source', then 119 * 'sourcep' is attached to 'targetp' without any other action being taken. 120 * 121 * In either case, 'sourcep' is detached. 122 * 123 * Requires: 124 * 125 * \li 'sourcep' is not NULL and '*source' is not NULL 126 * \li 'targetp' is not NULL and '*source' is NULL 127 * 128 * Ensures: 129 * 130 * \li On success, '*targetp' points to a valid task pool. 131 * \li On success, '*sourcep' points to NULL. 132 * 133 * Returns: 134 * 135 * \li #ISC_R_SUCCESS 136 * \li #ISC_R_NOMEMORY 137 */ 138 139 void 140 isc_pool_destroy(isc_pool_t **poolp); 141 /*%< 142 * Destroy a task pool. The tasks in the pool are detached but not 143 * shut down. 144 * 145 * Requires: 146 * \li '*poolp' is a valid task pool. 147 */ 148 149 ISC_LANG_ENDDECLS 150 151 #endif /* ISC_OBJPOOL_H */ 152