"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.16.7/lib/isc/include/isc/pool.h" (4 Sep 2020, 3490 Bytes) of package /linux/misc/dns/bind9/9.16.7/bind-9.16.7.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "pool.h" see the Fossies "Dox" file reference documentation.

    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 http://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 */