contrib/bind9/lib/isc/include/isc/pool.h

   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
  43 ISC_LANG_BEGINDECLS
  44
  45 /*****
  46  ***** Types.
  47  *****/
  48
  49 typedef void
  50 (*isc_pooldeallocator_t)(void **object);
  51
  52 typedef isc_result_t
  53 (*isc_poolinitializer_t)(void **target, void *arg);
  54
  55 typedef struct isc_pool isc_pool_t;
  56
  57 /*****
  58  ***** Functions.
  59  *****/
  60
  61 isc_result_t
  62 isc_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
  92 void *
  93 isc_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
 100 int
 101 isc_pool_count(isc_pool_t *pool);
 102 /*%<
 103  * Returns the number of objcts in the pool 'pool'.
 104  */
 105
 106 isc_result_t
 107 isc_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
 137 void
 138 isc_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
 147 ISC_LANG_ENDDECLS
 148
 149 #endif /* ISC_OBJPOOL_H */