"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/isc/include/isc/mem.h" (7 Sep 2020, 21109 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


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 "mem.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_MEM_H
   13 #define ISC_MEM_H 1
   14 
   15 /*! \file isc/mem.h */
   16 
   17 #include <stdbool.h>
   18 #include <stdio.h>
   19 
   20 #include <isc/json.h>
   21 #include <isc/lang.h>
   22 #include <isc/mutex.h>
   23 #include <isc/platform.h>
   24 #include <isc/types.h>
   25 #include <isc/xml.h>
   26 
   27 ISC_LANG_BEGINDECLS
   28 
   29 #define ISC_MEM_LOWATER 0
   30 #define ISC_MEM_HIWATER 1
   31 typedef void (*isc_mem_water_t)(void *, int);
   32 
   33 typedef void * (*isc_memalloc_t)(void *, size_t);
   34 typedef void (*isc_memfree_t)(void *, void *);
   35 
   36 /*%
   37  * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory
   38  * allocation and freeing by file and line number.
   39  */
   40 #ifndef ISC_MEM_TRACKLINES
   41 #define ISC_MEM_TRACKLINES 1
   42 #endif
   43 
   44 /*%
   45  * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
   46  * the requested space.  This will increase the size of each allocation.
   47  *
   48  * If we are performing a Coverity static analysis then ISC_MEM_CHECKOVERRUN
   49  * can hide bugs that would otherwise discovered so force to zero.
   50  */
   51 #ifdef __COVERITY__
   52 #undef ISC_MEM_CHECKOVERRUN
   53 #define ISC_MEM_CHECKOVERRUN 0
   54 #endif
   55 #ifndef ISC_MEM_CHECKOVERRUN
   56 #define ISC_MEM_CHECKOVERRUN 1
   57 #endif
   58 
   59 /*%
   60  * Define ISC_MEM_FILL=1 to fill each block of memory returned to the system
   61  * with the byte string '0xbe'.  This helps track down uninitialized pointers
   62  * and the like.  On freeing memory, the space is filled with '0xde' for
   63  * the same reasons.
   64  *
   65  * If we are performing a Coverity static analysis then ISC_MEM_FILL
   66  * can hide bugs that would otherwise discovered so force to zero.
   67  */
   68 #ifdef __COVERITY__
   69 #undef ISC_MEM_FILL
   70 #define ISC_MEM_FILL 0
   71 #endif
   72 #ifndef ISC_MEM_FILL
   73 #define ISC_MEM_FILL 1
   74 #endif
   75 
   76 /*%
   77  * Define ISC_MEMPOOL_NAMES=1 to make memory pools store a symbolic
   78  * name so that the leaking pool can be more readily identified in
   79  * case of a memory leak.
   80  */
   81 #ifndef ISC_MEMPOOL_NAMES
   82 #define ISC_MEMPOOL_NAMES 1
   83 #endif
   84 
   85 LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging;
   86 LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_defaultflags;
   87 
   88 /*@{*/
   89 #define ISC_MEM_DEBUGTRACE      0x00000001U
   90 #define ISC_MEM_DEBUGRECORD     0x00000002U
   91 #define ISC_MEM_DEBUGUSAGE      0x00000004U
   92 #define ISC_MEM_DEBUGSIZE       0x00000008U
   93 #define ISC_MEM_DEBUGCTX        0x00000010U
   94 #define ISC_MEM_DEBUGALL        0x0000001FU
   95 /*!<
   96  * The variable isc_mem_debugging holds a set of flags for
   97  * turning certain memory debugging options on or off at
   98  * runtime.  It is initialized to the value ISC_MEM_DEGBUGGING,
   99  * which is 0 by default but may be overridden at compile time.
  100  * The following flags can be specified:
  101  *
  102  * \li #ISC_MEM_DEBUGTRACE
  103  *  Log each allocation and free to isc_lctx.
  104  *
  105  * \li #ISC_MEM_DEBUGRECORD
  106  *  Remember each allocation, and match them up on free.
  107  *  Crash if a free doesn't match an allocation.
  108  *
  109  * \li #ISC_MEM_DEBUGUSAGE
  110  *  If a hi_water mark is set, print the maximum inuse memory
  111  *  every time it is raised once it exceeds the hi_water mark.
  112  *
  113  * \li #ISC_MEM_DEBUGSIZE
  114  *  Check the size argument being passed to isc_mem_put() matches
  115  *  that passed to isc_mem_get().
  116  *
  117  * \li #ISC_MEM_DEBUGCTX
  118  *  Check the mctx argument being passed to isc_mem_put() matches
  119  *  that passed to isc_mem_get().
  120  */
  121 /*@}*/
  122 
  123 #if ISC_MEM_TRACKLINES
  124 #define _ISC_MEM_FILELINE   , __FILE__, __LINE__
  125 #define _ISC_MEM_FLARG      , const char *, unsigned int
  126 #else
  127 #define _ISC_MEM_FILELINE
  128 #define _ISC_MEM_FLARG
  129 #endif
  130 
  131 /*!
  132  * Define ISC_MEM_USE_INTERNAL_MALLOC=1 to use the internal malloc()
  133  * implementation in preference to the system one.  The internal malloc()
  134  * is very space-efficient, and quite fast on uniprocessor systems.  It
  135  * performs poorly on multiprocessor machines.
  136  * JT: we can overcome the performance issue on multiprocessor machines
  137  * by carefully separating memory contexts.
  138  */
  139 
  140 #ifndef ISC_MEM_USE_INTERNAL_MALLOC
  141 #define ISC_MEM_USE_INTERNAL_MALLOC 1
  142 #endif
  143 
  144 /*
  145  * Flags for isc_mem_create2()calls.
  146  */
  147 #define ISC_MEMFLAG_NOLOCK  0x00000001   /* no lock is necessary */
  148 #define ISC_MEMFLAG_INTERNAL    0x00000002   /* use internal malloc */
  149 #if ISC_MEM_USE_INTERNAL_MALLOC
  150 #define ISC_MEMFLAG_DEFAULT     ISC_MEMFLAG_INTERNAL
  151 #else
  152 #define ISC_MEMFLAG_DEFAULT     0
  153 #endif
  154 
  155 
  156 /*%<
  157  * We use either isc___mem (three underscores) or isc__mem (two) depending on
  158  * whether it's for BIND9's internal purpose (with -DBIND9) or generic export
  159  * library.
  160  */
  161 #define ISCMEMFUNC(sfx) isc__mem_ ## sfx
  162 #define ISCMEMPOOLFUNC(sfx) isc__mempool_ ## sfx
  163 
  164 #define isc_mem_get(c, s)   ISCMEMFUNC(get)((c), (s) _ISC_MEM_FILELINE)
  165 #define isc_mem_allocate(c, s)  ISCMEMFUNC(allocate)((c), (s) _ISC_MEM_FILELINE)
  166 #define isc_mem_reallocate(c, p, s) ISCMEMFUNC(reallocate)((c), (p), (s) _ISC_MEM_FILELINE)
  167 #define isc_mem_strdup(c, p)    ISCMEMFUNC(strdup)((c), (p) _ISC_MEM_FILELINE)
  168 #define isc_mempool_get(c)  ISCMEMPOOLFUNC(get)((c) _ISC_MEM_FILELINE)
  169 
  170 /*%
  171  * isc_mem_putanddetach() is a convenience function for use where you
  172  * have a structure with an attached memory context.
  173  *
  174  * Given:
  175  *
  176  * \code
  177  * struct {
  178  *  ...
  179  *  isc_mem_t *mctx;
  180  *  ...
  181  * } *ptr;
  182  *
  183  * isc_mem_t *mctx;
  184  *
  185  * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
  186  * \endcode
  187  *
  188  * is the equivalent of:
  189  *
  190  * \code
  191  * mctx = NULL;
  192  * isc_mem_attach(ptr->mctx, &mctx);
  193  * isc_mem_detach(&ptr->mctx);
  194  * isc_mem_put(mctx, ptr, sizeof(*ptr));
  195  * isc_mem_detach(&mctx);
  196  * \endcode
  197  */
  198 
  199 /*% memory and memory pool methods */
  200 typedef struct isc_memmethods {
  201     void (*attach)(isc_mem_t *source, isc_mem_t **targetp);
  202     void (*detach)(isc_mem_t **mctxp);
  203     void (*destroy)(isc_mem_t **mctxp);
  204     void *(*memget)(isc_mem_t *mctx, size_t size _ISC_MEM_FLARG);
  205     void (*memput)(isc_mem_t *mctx, void *ptr, size_t size _ISC_MEM_FLARG);
  206     void (*memputanddetach)(isc_mem_t **mctxp, void *ptr,
  207                 size_t size _ISC_MEM_FLARG);
  208     void *(*memallocate)(isc_mem_t *mctx, size_t size _ISC_MEM_FLARG);
  209     void *(*memreallocate)(isc_mem_t *mctx, void *ptr,
  210                    size_t size _ISC_MEM_FLARG);
  211     char *(*memstrdup)(isc_mem_t *mctx, const char *s _ISC_MEM_FLARG);
  212     void (*memfree)(isc_mem_t *mctx, void *ptr _ISC_MEM_FLARG);
  213     void (*setdestroycheck)(isc_mem_t *mctx, bool flag);
  214     void (*setwater)(isc_mem_t *ctx, isc_mem_water_t water,
  215              void *water_arg, size_t hiwater, size_t lowater);
  216     void (*waterack)(isc_mem_t *ctx, int flag);
  217     size_t (*inuse)(isc_mem_t *mctx);
  218     size_t (*maxinuse)(isc_mem_t *mctx);
  219     size_t (*total)(isc_mem_t *mctx);
  220     bool (*isovermem)(isc_mem_t *mctx);
  221     isc_result_t (*mpcreate)(isc_mem_t *mctx, size_t size,
  222                  isc_mempool_t **mpctxp);
  223 } isc_memmethods_t;
  224 
  225 typedef struct isc_mempoolmethods {
  226     void (*destroy)(isc_mempool_t **mpctxp);
  227     void *(*get)(isc_mempool_t *mpctx _ISC_MEM_FLARG);
  228     void (*put)(isc_mempool_t *mpctx, void *mem _ISC_MEM_FLARG);
  229     unsigned int (*getallocated)(isc_mempool_t *mpctx);
  230     void (*setmaxalloc)(isc_mempool_t *mpctx, unsigned int limit);
  231     void (*setfreemax)(isc_mempool_t *mpctx, unsigned int limit);
  232     void (*setname)(isc_mempool_t *mpctx, const char *name);
  233     void (*associatelock)(isc_mempool_t *mpctx, isc_mutex_t *lock);
  234     void (*setfillcount)(isc_mempool_t *mpctx, unsigned int limit);
  235 } isc_mempoolmethods_t;
  236 
  237 /*%
  238  * This structure is actually just the common prefix of a memory context
  239  * implementation's version of an isc_mem_t.
  240  * \brief
  241  * Direct use of this structure by clients is forbidden.  mctx implementations
  242  * may change the structure.  'magic' must be ISCAPI_MCTX_MAGIC for any of the
  243  * isc_mem_ routines to work.  mctx implementations must maintain all mctx
  244  * invariants.
  245  */
  246 struct isc_mem {
  247     unsigned int        impmagic;
  248     unsigned int        magic;
  249     isc_memmethods_t    *methods;
  250 };
  251 
  252 #define ISCAPI_MCTX_MAGIC   ISC_MAGIC('A','m','c','x')
  253 #define ISCAPI_MCTX_VALID(m)    ((m) != NULL && \
  254                  (m)->magic == ISCAPI_MCTX_MAGIC)
  255 
  256 /*%
  257  * This is the common prefix of a memory pool context.  The same note as
  258  * that for the mem structure applies.
  259  */
  260 struct isc_mempool {
  261     unsigned int        impmagic;
  262     unsigned int        magic;
  263     isc_mempoolmethods_t    *methods;
  264 };
  265 
  266 #define ISCAPI_MPOOL_MAGIC  ISC_MAGIC('A','m','p','l')
  267 #define ISCAPI_MPOOL_VALID(mp)  ((mp) != NULL && \
  268                  (mp)->magic == ISCAPI_MPOOL_MAGIC)
  269 
  270 #define isc_mem_put(c, p, s) \
  271     do { \
  272         ISCMEMFUNC(put)((c), (p), (s) _ISC_MEM_FILELINE);   \
  273         (p) = NULL; \
  274     } while (0)
  275 #define isc_mem_putanddetach(c, p, s) \
  276     do { \
  277         ISCMEMFUNC(putanddetach)((c), (p), (s) _ISC_MEM_FILELINE); \
  278         (p) = NULL; \
  279     } while (0)
  280 #define isc_mem_free(c, p) \
  281     do { \
  282         ISCMEMFUNC(free)((c), (p) _ISC_MEM_FILELINE);   \
  283         (p) = NULL; \
  284     } while (0)
  285 #define isc_mempool_put(c, p) \
  286     do { \
  287         ISCMEMPOOLFUNC(put)((c), (p) _ISC_MEM_FILELINE);    \
  288         (p) = NULL; \
  289     } while (0)
  290 
  291 /*@{*/
  292 isc_result_t
  293 isc_mem_create(size_t max_size, size_t target_size,
  294            isc_mem_t **mctxp);
  295 
  296 isc_result_t
  297 isc_mem_create2(size_t max_size, size_t target_size,
  298         isc_mem_t **mctxp, unsigned int flags);
  299 
  300 isc_result_t
  301 isc_mem_createx(size_t max_size, size_t target_size,
  302         isc_memalloc_t memalloc, isc_memfree_t memfree,
  303         void *arg, isc_mem_t **mctxp);
  304 
  305 isc_result_t
  306 isc_mem_createx2(size_t max_size, size_t target_size,
  307          isc_memalloc_t memalloc, isc_memfree_t memfree,
  308          void *arg, isc_mem_t **mctxp, unsigned int flags);
  309 
  310 /*!<
  311  * \brief Create a memory context.
  312  *
  313  * 'max_size' and 'target_size' are tuning parameters.  When
  314  * ISC_MEMFLAG_INTERNAL is set, allocations smaller than 'max_size'
  315  * will be satisfied by getting blocks of size 'target_size' from the
  316  * system allocator and breaking them up into pieces; larger allocations
  317  * will use the system allocator directly. If 'max_size' and/or
  318  * 'target_size' are zero, default values will be * used.  When
  319  * ISC_MEMFLAG_INTERNAL is not set, 'target_size' is ignored.
  320  *
  321  * 'max_size' is also used to size the statistics arrays and the array
  322  * used to record active memory when ISC_MEM_DEBUGRECORD is set.  Setting
  323  * 'max_size' too low can have detrimental effects on performance.
  324  *
  325  * A memory context created using isc_mem_createx() will obtain
  326  * memory from the system by calling 'memalloc' and 'memfree',
  327  * passing them the argument 'arg'.  A memory context created
  328  * using isc_mem_create() will use the standard library malloc()
  329  * and free().
  330  *
  331  * If ISC_MEMFLAG_NOLOCK is set in 'flags', the corresponding memory context
  332  * will be accessed without locking.  The user who creates the context must
  333  * ensure there be no race.  Since this can be a source of bug, it is generally
  334  * inadvisable to use this flag unless the user is very sure about the race
  335  * condition and the access to the object is highly performance sensitive.
  336  *
  337  * Requires:
  338  * mctxp != NULL && *mctxp == NULL */
  339 /*@}*/
  340 
  341 /*@{*/
  342 void
  343 isc_mem_attach(isc_mem_t *, isc_mem_t **);
  344 void
  345 isc_mem_detach(isc_mem_t **);
  346 /*!<
  347  * \brief Attach to / detach from a memory context.
  348  *
  349  * This is intended for applications that use multiple memory contexts
  350  * in such a way that it is not obvious when the last allocations from
  351  * a given context has been freed and destroying the context is safe.
  352  *
  353  * Most applications do not need to call these functions as they can
  354  * simply create a single memory context at the beginning of main()
  355  * and destroy it at the end of main(), thereby guaranteeing that it
  356  * is not destroyed while there are outstanding allocations.
  357  */
  358 /*@}*/
  359 
  360 void
  361 isc_mem_destroy(isc_mem_t **);
  362 /*%<
  363  * Destroy a memory context.
  364  */
  365 
  366 isc_result_t
  367 isc_mem_ondestroy(isc_mem_t *ctx,
  368           isc_task_t *task,
  369           isc_event_t **event);
  370 /*%<
  371  * Request to be notified with an event when a memory context has
  372  * been successfully destroyed.
  373  */
  374 
  375 void
  376 isc_mem_stats(isc_mem_t *mctx, FILE *out);
  377 /*%<
  378  * Print memory usage statistics for 'mctx' on the stream 'out'.
  379  */
  380 
  381 void
  382 isc_mem_setdestroycheck(isc_mem_t *mctx,
  383             bool on);
  384 /*%<
  385  * If 'on' is true, 'mctx' will check for memory leaks when
  386  * destroyed and abort the program if any are present.
  387  */
  388 
  389 /*@{*/
  390 void
  391 isc_mem_setquota(isc_mem_t *, size_t);
  392 size_t
  393 isc_mem_getquota(isc_mem_t *);
  394 /*%<
  395  * Set/get the memory quota of 'mctx'.  This is a hard limit
  396  * on the amount of memory that may be allocated from mctx;
  397  * if it is exceeded, allocations will fail.
  398  */
  399 /*@}*/
  400 
  401 size_t
  402 isc_mem_inuse(isc_mem_t *mctx);
  403 /*%<
  404  * Get an estimate of the amount of memory in use in 'mctx', in bytes.
  405  * This includes quantization overhead, but does not include memory
  406  * allocated from the system but not yet used.
  407  */
  408 
  409 size_t
  410 isc_mem_maxinuse(isc_mem_t *mctx);
  411 /*%<
  412  * Get an estimate of the largest amount of memory that has been in
  413  * use in 'mctx' at any time.
  414  */
  415 
  416 size_t
  417 isc_mem_total(isc_mem_t *mctx);
  418 /*%<
  419  * Get the total amount of memory in 'mctx', in bytes, including memory
  420  * not yet used.
  421  */
  422 
  423 bool
  424 isc_mem_isovermem(isc_mem_t *mctx);
  425 /*%<
  426  * Return true iff the memory context is in "over memory" state, i.e.,
  427  * a hiwater mark has been set and the used amount of memory has exceeds
  428  * the mark.
  429  */
  430 
  431 void
  432 isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
  433          size_t hiwater, size_t lowater);
  434 /*%<
  435  * Set high and low water marks for this memory context.
  436  *
  437  * When the memory usage of 'mctx' exceeds 'hiwater',
  438  * '(water)(water_arg, #ISC_MEM_HIWATER)' will be called.  'water' needs to
  439  * call isc_mem_waterack() with #ISC_MEM_HIWATER to acknowledge the state
  440  * change.  'water' may be called multiple times.
  441  *
  442  * When the usage drops below 'lowater', 'water' will again be called, this
  443  * time with #ISC_MEM_LOWATER.  'water' need to calls isc_mem_waterack() with
  444  * #ISC_MEM_LOWATER to acknowledge the change.
  445  *
  446  *  static void
  447  *  water(void *arg, int mark) {
  448  *      struct foo *foo = arg;
  449  *
  450  *      LOCK(&foo->marklock);
  451  *      if (foo->mark != mark) {
  452  *          foo->mark = mark;
  453  *          ....
  454  *          isc_mem_waterack(foo->mctx, mark);
  455  *      }
  456  *      UNLOCK(&foo->marklock);
  457  *  }
  458  *
  459  * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
  460  * ignored and the state is reset.
  461  *
  462  * Requires:
  463  *
  464  *  'water' is not NULL.
  465  *  hi_water >= lo_water
  466  */
  467 
  468 void
  469 isc_mem_waterack(isc_mem_t *ctx, int mark);
  470 /*%<
  471  * Called to acknowledge changes in signaled by calls to 'water'.
  472  */
  473 
  474 void
  475 isc_mem_printactive(isc_mem_t *mctx, FILE *file);
  476 /*%<
  477  * Print to 'file' all active memory in 'mctx'.
  478  *
  479  * Requires ISC_MEM_DEBUGRECORD to have been set.
  480  */
  481 
  482 void
  483 isc_mem_printallactive(FILE *file);
  484 /*%<
  485  * Print to 'file' all active memory in all contexts.
  486  *
  487  * Requires ISC_MEM_DEBUGRECORD to have been set.
  488  */
  489 
  490 void
  491 isc_mem_checkdestroyed(FILE *file);
  492 /*%<
  493  * Check that all memory contexts have been destroyed.
  494  * Prints out those that have not been.
  495  * Fatally fails if there are still active contexts.
  496  */
  497 
  498 unsigned int
  499 isc_mem_references(isc_mem_t *ctx);
  500 /*%<
  501  * Return the current reference count.
  502  */
  503 
  504 void
  505 isc_mem_setname(isc_mem_t *ctx, const char *name, void *tag);
  506 /*%<
  507  * Name 'ctx'.
  508  *
  509  * Notes:
  510  *
  511  *\li   Only the first 15 characters of 'name' will be copied.
  512  *
  513  *\li   'tag' is for debugging purposes only.
  514  *
  515  * Requires:
  516  *
  517  *\li   'ctx' is a valid ctx.
  518  */
  519 
  520 const char *
  521 isc_mem_getname(isc_mem_t *ctx);
  522 /*%<
  523  * Get the name of 'ctx', as previously set using isc_mem_setname().
  524  *
  525  * Requires:
  526  *\li   'ctx' is a valid ctx.
  527  *
  528  * Returns:
  529  *\li   A non-NULL pointer to a null-terminated string.
  530  *  If the ctx has not been named, the string is
  531  *  empty.
  532  */
  533 
  534 void *
  535 isc_mem_gettag(isc_mem_t *ctx);
  536 /*%<
  537  * Get the tag value for  'task', as previously set using isc_mem_setname().
  538  *
  539  * Requires:
  540  *\li   'ctx' is a valid ctx.
  541  *
  542  * Notes:
  543  *\li   This function is for debugging purposes only.
  544  *
  545  * Requires:
  546  *\li   'ctx' is a valid task.
  547  */
  548 
  549 #ifdef HAVE_LIBXML2
  550 int
  551 isc_mem_renderxml(xmlTextWriterPtr writer);
  552 /*%<
  553  * Render all contexts' statistics and status in XML for writer.
  554  */
  555 #endif /* HAVE_LIBXML2 */
  556 
  557 #ifdef HAVE_JSON
  558 isc_result_t
  559 isc_mem_renderjson(json_object *memobj);
  560 /*%<
  561  * Render all contexts' statistics and status in JSON.
  562  */
  563 #endif /* HAVE_JSON */
  564 
  565 
  566 /*
  567  * Memory pools
  568  */
  569 
  570 isc_result_t
  571 isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
  572 /*%<
  573  * Create a memory pool.
  574  *
  575  * Requires:
  576  *\li   mctx is a valid memory context.
  577  *\li   size > 0
  578  *\li   mpctxp != NULL and *mpctxp == NULL
  579  *
  580  * Defaults:
  581  *\li   maxalloc = UINT_MAX
  582  *\li   freemax = 1
  583  *\li   fillcount = 1
  584  *
  585  * Returns:
  586  *\li   #ISC_R_NOMEMORY     -- not enough memory to create pool
  587  *\li   #ISC_R_SUCCESS      -- all is well.
  588  */
  589 
  590 void
  591 isc_mempool_destroy(isc_mempool_t **mpctxp);
  592 /*%<
  593  * Destroy a memory pool.
  594  *
  595  * Requires:
  596  *\li   mpctxp != NULL && *mpctxp is a valid pool.
  597  *\li   The pool has no un"put" allocations outstanding
  598  */
  599 
  600 void
  601 isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
  602 /*%<
  603  * Associate a name with a memory pool.  At most 15 characters may be used.
  604  *
  605  * Requires:
  606  *\li   mpctx is a valid pool.
  607  *\li   name != NULL;
  608  */
  609 
  610 void
  611 isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
  612 /*%<
  613  * Associate a lock with this memory pool.
  614  *
  615  * This lock is used when getting or putting items using this memory pool,
  616  * and it is also used to set or get internal state via the isc_mempool_get*()
  617  * and isc_mempool_set*() set of functions.
  618  *
  619  * Multiple pools can each share a single lock.  For instance, if "manager"
  620  * type object contained pools for various sizes of events, and each of
  621  * these pools used a common lock.  Note that this lock must NEVER be used
  622  * by other than mempool routines once it is given to a pool, since that can
  623  * easily cause double locking.
  624  *
  625  * Requires:
  626  *
  627  *\li   mpctpx is a valid pool.
  628  *
  629  *\li   lock != NULL.
  630  *
  631  *\li   No previous lock is assigned to this pool.
  632  *
  633  *\li   The lock is initialized before calling this function via the normal
  634  *  means of doing that.
  635  */
  636 
  637 /*
  638  * The following functions get/set various parameters.  Note that due to
  639  * the unlocked nature of pools these are potentially random values unless
  640  * the imposed externally provided locking protocols are followed.
  641  *
  642  * Also note that the quota limits will not always take immediate effect.
  643  * For instance, setting "maxalloc" to a number smaller than the currently
  644  * allocated count is permitted.  New allocations will be refused until
  645  * the count drops below this threshold.
  646  *
  647  * All functions require (in addition to other requirements):
  648  *  mpctx is a valid memory pool
  649  */
  650 
  651 unsigned int
  652 isc_mempool_getfreemax(isc_mempool_t *mpctx);
  653 /*%<
  654  * Returns the maximum allowed size of the free list.
  655  */
  656 
  657 void
  658 isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
  659 /*%<
  660  * Sets the maximum allowed size of the free list.
  661  */
  662 
  663 unsigned int
  664 isc_mempool_getfreecount(isc_mempool_t *mpctx);
  665 /*%<
  666  * Returns current size of the free list.
  667  */
  668 
  669 unsigned int
  670 isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
  671 /*!<
  672  * Returns the maximum allowed number of allocations.
  673  */
  674 
  675 void
  676 isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
  677 /*%<
  678  * Sets the maximum allowed number of allocations.
  679  *
  680  * Additional requirements:
  681  *\li   limit > 0
  682  */
  683 
  684 unsigned int
  685 isc_mempool_getallocated(isc_mempool_t *mpctx);
  686 /*%<
  687  * Returns the number of items allocated from this pool.
  688  */
  689 
  690 unsigned int
  691 isc_mempool_getfillcount(isc_mempool_t *mpctx);
  692 /*%<
  693  * Returns the number of items allocated as a block from the parent memory
  694  * context when the free list is empty.
  695  */
  696 
  697 void
  698 isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
  699 /*%<
  700  * Sets the fillcount.
  701  *
  702  * Additional requirements:
  703  *\li   limit > 0
  704  */
  705 
  706 
  707 /*
  708  * Pseudo-private functions for use via macros.  Do not call directly.
  709  */
  710 void *
  711 ISCMEMFUNC(get)(isc_mem_t *, size_t _ISC_MEM_FLARG);
  712 void
  713 ISCMEMFUNC(putanddetach)(isc_mem_t **, void *, size_t _ISC_MEM_FLARG);
  714 void
  715 ISCMEMFUNC(put)(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
  716 void *
  717 ISCMEMFUNC(allocate)(isc_mem_t *, size_t _ISC_MEM_FLARG);
  718 void *
  719 ISCMEMFUNC(reallocate)(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
  720 void
  721 ISCMEMFUNC(free)(isc_mem_t *, void * _ISC_MEM_FLARG);
  722 char *
  723 ISCMEMFUNC(strdup)(isc_mem_t *, const char *_ISC_MEM_FLARG);
  724 void *
  725 ISCMEMPOOLFUNC(get)(isc_mempool_t * _ISC_MEM_FLARG);
  726 void
  727 ISCMEMPOOLFUNC(put)(isc_mempool_t *, void * _ISC_MEM_FLARG);
  728 
  729 /*%<
  730  * See isc_mem_create2() above.
  731  */
  732 typedef isc_result_t
  733 (*isc_memcreatefunc_t)(size_t init_max_size, size_t target_size,
  734                isc_mem_t **ctxp, unsigned int flags);
  735 
  736 isc_result_t
  737 isc_mem_register(isc_memcreatefunc_t createfunc);
  738 /*%<
  739  * Register a new memory management implementation and add it to the list of
  740  * supported implementations.  This function must be called when a different
  741  * memory management library is used than the one contained in the ISC library.
  742  */
  743 
  744 isc_result_t
  745 isc__mem_register(void);
  746 /*%<
  747  * A short cut function that specifies the memory management module in the ISC
  748  * library for isc_mem_register().  An application that uses the ISC library
  749  * usually do not have to care about this function: it would call
  750  * isc_lib_register(), which internally calls this function.
  751  */
  752 
  753 ISC_LANG_ENDDECLS
  754 
  755 #endif /* ISC_MEM_H */