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