1254322Serwin/* 2254322Serwin * Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC") 3254322Serwin * 4254322Serwin * Permission to use, copy, modify, and/or distribute this software for any 5254322Serwin * purpose with or without fee is hereby granted, provided that the above 6254322Serwin * copyright notice and this permission notice appear in all copies. 7254322Serwin * 8254322Serwin * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 9254322Serwin * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10254322Serwin * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 11254322Serwin * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12254322Serwin * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13254322Serwin * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 14254322Serwin * PERFORMANCE OF THIS SOFTWARE. 15254322Serwin */ 16254322Serwin 17254322Serwin#ifndef ISC_OBJPOOL_H 18254322Serwin#define ISC_OBJPOOL_H 1 19254322Serwin 20254322Serwin/***** 21254322Serwin ***** Module Info 22254322Serwin *****/ 23254322Serwin 24254322Serwin/*! \file isc/pool.h 25254322Serwin * \brief An object pool is a mechanism for sharing a small pool of 26254322Serwin * fungible objects among a large number of objects that depend on them. 27254322Serwin * 28254322Serwin * This is useful, for example, when it causes performance problems for 29254322Serwin * large number of zones to share a single memory context or task object, 30254322Serwin * but it would create a different set of problems for them each to have an 31254322Serwin * independent task or memory context. 32254322Serwin */ 33254322Serwin 34254322Serwin 35254322Serwin/*** 36254322Serwin *** Imports. 37254322Serwin ***/ 38254322Serwin 39254322Serwin#include <isc/lang.h> 40254322Serwin#include <isc/mem.h> 41254322Serwin#include <isc/types.h> 42254322Serwin 43254322SerwinISC_LANG_BEGINDECLS 44254322Serwin 45254322Serwin/***** 46254322Serwin ***** Types. 47254322Serwin *****/ 48254322Serwin 49254322Serwintypedef void 50254322Serwin(*isc_pooldeallocator_t)(void **object); 51254322Serwin 52254322Serwintypedef isc_result_t 53254322Serwin(*isc_poolinitializer_t)(void **target, void *arg); 54254322Serwin 55254322Serwintypedef struct isc_pool isc_pool_t; 56254322Serwin 57254322Serwin/***** 58254322Serwin ***** Functions. 59254322Serwin *****/ 60254322Serwin 61254322Serwinisc_result_t 62254322Serwinisc_pool_create(isc_mem_t *mctx, unsigned int count, 63254322Serwin isc_pooldeallocator_t free, 64254322Serwin isc_poolinitializer_t init, void *initarg, 65254322Serwin isc_pool_t **poolp); 66254322Serwin/*%< 67254322Serwin * Create a pool of "count" object pointers. If 'free' is not NULL, 68254322Serwin * it points to a function that will detach the objects. 'init' 69254322Serwin * points to a function that will initialize the arguments, and 70254322Serwin * 'arg' to an argument to be passed into that function (for example, 71254322Serwin * a relevant manager or context object). 72254322Serwin * 73254322Serwin * Requires: 74254322Serwin * 75254322Serwin *\li 'mctx' is a valid memory context. 76254322Serwin * 77254322Serwin *\li init != NULL 78254322Serwin * 79254322Serwin *\li poolp != NULL && *poolp == NULL 80254322Serwin * 81254322Serwin * Ensures: 82254322Serwin * 83254322Serwin *\li On success, '*poolp' points to the new object pool. 84254322Serwin * 85254322Serwin * Returns: 86254322Serwin * 87254322Serwin *\li #ISC_R_SUCCESS 88254322Serwin *\li #ISC_R_NOMEMORY 89254322Serwin *\li #ISC_R_UNEXPECTED 90254322Serwin */ 91254322Serwin 92254322Serwinvoid * 93254322Serwinisc_pool_get(isc_pool_t *pool); 94254322Serwin/*%< 95254322Serwin * Returns a pointer to an object from the pool. Currently the object 96254322Serwin * is chosen from the pool at random. (This may be changed in the future 97254322Serwin * to something that guaratees balance.) 98254322Serwin */ 99254322Serwin 100254322Serwinint 101254322Serwinisc_pool_count(isc_pool_t *pool); 102254322Serwin/*%< 103254322Serwin * Returns the number of objcts in the pool 'pool'. 104254322Serwin */ 105254322Serwin 106254322Serwinisc_result_t 107254322Serwinisc_pool_expand(isc_pool_t **sourcep, unsigned int count, isc_pool_t **targetp); 108254322Serwin 109254322Serwin/*%< 110254322Serwin * If 'size' is larger than the number of objects in the pool pointed to by 111254322Serwin * 'sourcep', then a new pool of size 'count' is allocated, the existing 112254322Serwin * objects are copied into it, additional ones created to bring the 113254322Serwin * total number up to 'count', and the resulting pool is attached to 114254322Serwin * 'targetp'. 115254322Serwin * 116254322Serwin * If 'count' is less than or equal to the number of objects in 'source', then 117254322Serwin * 'sourcep' is attached to 'targetp' without any other action being taken. 118254322Serwin * 119254322Serwin * In either case, 'sourcep' is detached. 120254322Serwin * 121254322Serwin * Requires: 122254322Serwin * 123254322Serwin * \li 'sourcep' is not NULL and '*source' is not NULL 124254322Serwin * \li 'targetp' is not NULL and '*source' is NULL 125254322Serwin * 126254322Serwin * Ensures: 127254322Serwin * 128254322Serwin * \li On success, '*targetp' points to a valid task pool. 129254322Serwin * \li On success, '*sourcep' points to NULL. 130254322Serwin * 131254322Serwin * Returns: 132254322Serwin * 133254322Serwin * \li #ISC_R_SUCCESS 134254322Serwin * \li #ISC_R_NOMEMORY 135254322Serwin */ 136254322Serwin 137254322Serwinvoid 138254322Serwinisc_pool_destroy(isc_pool_t **poolp); 139254322Serwin/*%< 140254322Serwin * Destroy a task pool. The tasks in the pool are detached but not 141254322Serwin * shut down. 142254322Serwin * 143254322Serwin * Requires: 144254322Serwin * \li '*poolp' is a valid task pool. 145254322Serwin */ 146254322Serwin 147254322SerwinISC_LANG_ENDDECLS 148254322Serwin 149254322Serwin#endif /* ISC_OBJPOOL_H */ 150