contrib/bind-9.2.4rc7/lib/isc/include/isc/mem.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1997-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: mem.h,v 1.54.2.1 2004/03/09 06:11:58 marka Exp $ */
  19
  20 #ifndef ISC_MEM_H
  21 #define ISC_MEM_H 1
  22
  23 #include <stdio.h>
  24
  25 #include <isc/lang.h>
  26 #include <isc/mutex.h>
  27 #include <isc/platform.h>
  28 #include <isc/types.h>
  29
  30 ISC_LANG_BEGINDECLS
  31
  32 #define ISC_MEM_LOWATER 0
  33 #define ISC_MEM_HIWATER 1
  34 typedef void (*isc_mem_water_t)(void *, int);
  35
  36 typedef void * (*isc_memalloc_t)(void *, size_t);
  37 typedef void (*isc_memfree_t)(void *, void *);
  38
  39 /*
  40  * ISC_MEM_DEBUG is enabled by default; set ISC_MEM_DEBUG=0 to disable it.
  41  */
  42 #ifndef ISC_MEM_DEBUG
  43 #define ISC_MEM_DEBUG 1
  44 #endif
  45
  46 /*
  47  * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory allocation
  48  * and freeing by file and line number.
  49  */
  50 #ifndef ISC_MEM_TRACKLINES
  51 #define ISC_MEM_TRACKLINES 0
  52 #endif
  53
  54 /*
  55  * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
  56  * the requested space.  This will increase the size of each allocation.
  57  */
  58 #ifndef ISC_MEM_CHECKOVERRUN
  59 #define ISC_MEM_CHECKOVERRUN 0
  60 #endif
  61
  62 /*
  63  * Define ISC_MEM_FILL to fill each block of memory returned to the system
  64  * with the byte string '0xbe'.  This helps track down uninitialized pointers
  65  * and the like.  On freeing memory, the space is filled with '0xde' for
  66  * the same reasons.
  67  */
  68 #ifndef ISC_MEM_FILL
  69 #define ISC_MEM_FILL 1
  70 #endif
  71
  72 /*
  73  * Define this to turn on memory pool names.
  74  */
  75 #ifndef ISC_MEMPOOL_NAMES
  76 #define ISC_MEMPOOL_NAMES 1
  77 #endif
  78
  79 /*
  80  * _DEBUGTRACE
  81  *      log (to isc_lctx) each allocation and free.
  82  *
  83  * _DEBUGRECORD
  84  *      remember each allocation, and match them up on free.  Crash if
  85  *      a free doesn't match an allocation
  86  * _DEBUGUSAGE
  87  *      if a hi_water mark is set print the maximium inuse memory every
  88  *      time it is raised once it exceeds the hi_water mark
  89  */
  90 LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging;
  91 #define ISC_MEM_DEBUGTRACE              0x00000001U
  92 #define ISC_MEM_DEBUGRECORD             0x00000002U
  93 #define ISC_MEM_DEBUGUSAGE              0x00000004U
  94
  95 #if ISC_MEM_TRACKLINES
  96 #define _ISC_MEM_FILELINE       , __FILE__, __LINE__
  97 #define _ISC_MEM_FLARG          , const char *, int
  98 #else
  99 #define _ISC_MEM_FILELINE
 100 #define _ISC_MEM_FLARG
 101 #endif
 102
 103 #define isc_mem_get(c, s)       isc__mem_get((c), (s) _ISC_MEM_FILELINE)
 104 #define isc_mem_allocate(c, s)  isc__mem_allocate((c), (s) _ISC_MEM_FILELINE)
 105 #define isc_mem_strdup(c, p)    isc__mem_strdup((c), (p) _ISC_MEM_FILELINE)
 106 #define isc_mempool_get(c)      isc__mempool_get((c) _ISC_MEM_FILELINE)
 107
 108 /*
 109  * isc_mem_putanddetach() is a convienence function for use where you
 110  * have a structure with an attached memory context.
 111  *
 112  * Given:
 113  *
 114  * struct {
 115  *      ...
 116  *      isc_mem_t *mctx;
 117  *      ...
 118  * } *ptr;
 119  *
 120  * isc_mem_t *mctx;
 121  *
 122  * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
 123  *
 124  * is the equivalent of:
 125  *
 126  * mctx = NULL;
 127  * isc_mem_attach(ptr->mctx, &mctx);
 128  * isc_mem_detach(&ptr->mctx);
 129  * isc_mem_put(mctx, ptr, sizeof(*ptr));
 130  * isc_mem_detach(&mctx);
 131  */
 132
 133 #if ISC_MEM_DEBUG
 134 #define isc_mem_put(c, p, s) \
 135         do { \
 136                 isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE); \
 137                 (p) = NULL; \
 138         } while (0)
 139 #define isc_mem_putanddetach(c, p, s) \
 140         do { \
 141                 isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE); \
 142                 (p) = NULL; \
 143         } while (0)
 144 #define isc_mem_free(c, p) \
 145         do { \
 146                 isc__mem_free((c), (p) _ISC_MEM_FILELINE); \
 147                 (p) = NULL; \
 148         } while (0)
 149 #define isc_mempool_put(c, p) \
 150         do { \
 151                 isc__mempool_put((c), (p) _ISC_MEM_FILELINE); \
 152                 (p) = NULL; \
 153         } while (0)
 154 #else
 155 #define isc_mem_put(c, p, s)    isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE)
 156 #define isc_mem_putanddetach(c, p, s) \
 157         isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE)
 158 #define isc_mem_free(c, p)      isc__mem_free((c), (p) _ISC_MEM_FILELINE)
 159 #define isc_mempool_put(c, p)   isc__mempool_put((c), (p) _ISC_MEM_FILELINE)
 160 #endif
 161
 162 isc_result_t
 163 isc_mem_create(size_t max_size, size_t target_size,
 164                             isc_mem_t **mctxp);
 165
 166 isc_result_t
 167 isc_mem_createx(size_t max_size, size_t target_size,
 168                              isc_memalloc_t memalloc, isc_memfree_t memfree,
 169                              void *arg, isc_mem_t **mctxp);
 170 /*
 171  * Create a memory context.
 172  *
 173  * 'max_size' and 'target_size' are tuning parameters.  When
 174  * ISC_MEM_USE_INTERNAL_MALLOC is true, allocations smaller than
 175  * 'max_size' will be satisfied by getting blocks of size
 176  * 'target_size' from the system allocator and breaking them up into
 177  * pieces; larger allocations will use the system allocator directly.
 178  * If 'max_size' and/or 'target_size' are zero, default values will be
 179  * used.  When ISC_MEM_USE_INTERNAL_MALLOC is false, 'max_size' and
 180  * 'target_size' are ignored.
 181  *
 182  * A memory context created using isc_mem_createx() will obtain
 183  * memory from the system by calling 'memalloc' and 'memfree',
 184  * passing them the argument 'arg'.  A memory context created
 185  * using isc_mem_create() will use the standard library malloc()
 186  * and free().
 187  *
 188  * Requires:
 189  * mctxp != NULL && *mctxp == NULL */
 190
 191 void
 192 isc_mem_attach(isc_mem_t *, isc_mem_t **);
 193 void
 194 isc_mem_detach(isc_mem_t **);
 195 /*
 196  * Attach to / detach from a memory context.
 197  *
 198  * This is intended for applications that use multiple memory contexts
 199  * in such a way that it is not obvious when the last allocations from
 200  * a given context has been freed and destroying the context is safe.
 201  *
 202  * Most applications do not need to call these functions as they can
 203  * simply create a single memory context at the beginning of main()
 204  * and destroy it at the end of main(), thereby guaranteeing that it
 205  * is not destroyed while there are outstanding allocations.
 206  */
 207
 208 void
 209 isc_mem_destroy(isc_mem_t **);
 210 /*
 211  * Destroy a memory context.
 212  */
 213
 214 isc_result_t
 215 isc_mem_ondestroy(isc_mem_t *ctx,
 216                                isc_task_t *task,
 217                                isc_event_t **event);
 218 /*
 219  * Request to be notified with an event when a memory context has
 220  * been successfully destroyed.
 221  */
 222
 223 void
 224 isc_mem_stats(isc_mem_t *mctx, FILE *out);
 225 /*
 226  * Print memory usage statistics for 'mctx' on the stream 'out'.
 227  */
 228
 229 void
 230 isc_mem_setdestroycheck(isc_mem_t *mctx,
 231                              isc_boolean_t on);
 232 /*
 233  * Iff 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
 234  * destroyed and abort the program if any are present.
 235  */
 236
 237 void
 238 isc_mem_setquota(isc_mem_t *, size_t);
 239 size_t
 240 isc_mem_getquota(isc_mem_t *);
 241 /*
 242  * Set/get the memory quota of 'mctx'.  This is a hard limit
 243  * on the amount of memory that may be allocated from mctx;
 244  * if it is exceeded, allocations will fail.
 245  */
 246
 247 size_t
 248 isc_mem_inuse(isc_mem_t *mctx);
 249 /*
 250  * Get an estimate of the number of memory in use in 'mctx', in bytes.
 251  * This includes quantization overhead, but does not include memory
 252  * allocated from the system but not yet used.
 253  */
 254
 255 void
 256 isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
 257                  size_t hiwater, size_t lowater);
 258 /*
 259  * Set high and low water marks for this memory context.  When the memory
 260  * usage of 'mctx' exceeds 'hiwater', '(water)(water_arg, ISC_MEM_HIWATER)'
 261  * will be called.  When the usage drops below 'lowater', 'water' will
 262  * again be called, this time with ISC_MEM_LOWATER.
 263  *
 264  * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
 265  * ignored and the state is reset.
 266  *
 267  * Requires:
 268  *
 269  *      'water' is not NULL.
 270  *      hi_water >= lo_water
 271  */
 272
 273 /*
 274  * Memory pools
 275  */
 276
 277 isc_result_t
 278 isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
 279 /*
 280  * Create a memory pool.
 281  *
 282  * Requires:
 283  *      mctx is a valid memory context.
 284  *      size > 0
 285  *      mpctxp != NULL and *mpctxp == NULL
 286  *
 287  * Defaults:
 288  *      maxalloc = UINT_MAX
 289  *      freemax = 1
 290  *      fillcount = 1
 291  *
 292  * Returns:
 293  *      ISC_R_NOMEMORY          -- not enough memory to create pool
 294  *      ISC_R_SUCCESS           -- all is well.
 295  */
 296
 297 void
 298 isc_mempool_destroy(isc_mempool_t **mpctxp);
 299 /*
 300  * Destroy a memory pool.
 301  *
 302  * Requires:
 303  *      mpctxp != NULL && *mpctxp is a valid pool.
 304  *      The pool has no un"put" allocations outstanding
 305  */
 306
 307 void
 308 isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
 309 /*
 310  * Associate a name with a memory pool.  At most 15 characters may be used.
 311  *
 312  * Requires:
 313  *      mpctx is a valid pool.
 314  *      name != NULL;
 315  */
 316
 317 void
 318 isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
 319 /*
 320  * Associate a lock with this memory pool.
 321  *
 322  * This lock is used when getting or putting items using this memory pool,
 323  * and it is also used to set or get internal state via the isc_mempool_get*()
 324  * and isc_mempool_set*() set of functions.
 325  *
 326  * Mutiple pools can each share a single lock.  For instance, if "manager"
 327  * type object contained pools for various sizes of events, and each of
 328  * these pools used a common lock.  Note that this lock must NEVER be used
 329  * by other than mempool routines once it is given to a pool, since that can
 330  * easily cause double locking.
 331  *
 332  * Requires:
 333  *
 334  *      mpctpx is a valid pool.
 335  *
 336  *      lock != NULL.
 337  *
 338  *      No previous lock is assigned to this pool.
 339  *
 340  *      The lock is initialized before calling this function via the normal
 341  *      means of doing that.
 342  */
 343
 344 /*
 345  * The following functions get/set various parameters.  Note that due to
 346  * the unlocked nature of pools these are potentially random values unless
 347  * the imposed externally provided locking protocols are followed.
 348  *
 349  * Also note that the quota limits will not always take immediate effect.
 350  * For instance, setting "maxalloc" to a number smaller than the currently
 351  * allocated count is permitted.  New allocations will be refused until
 352  * the count drops below this threshold.
 353  *
 354  * All functions require (in addition to other requirements):
 355  *      mpctx is a valid memory pool
 356  */
 357
 358 unsigned int
 359 isc_mempool_getfreemax(isc_mempool_t *mpctx);
 360 /*
 361  * Returns the maximum allowed size of the free list.
 362  */
 363
 364 void
 365 isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
 366 /*
 367  * Sets the maximum allowed size of the free list.
 368  */
 369
 370 unsigned int
 371 isc_mempool_getfreecount(isc_mempool_t *mpctx);
 372 /*
 373  * Returns current size of the free list.
 374  */
 375
 376 unsigned int
 377 isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
 378 /*
 379  * Returns the maximum allowed number of allocations.
 380  */
 381
 382 void
 383 isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
 384 /*
 385  * Sets the maximum allowed number of allocations.
 386  *
 387  * Additional requirements:
 388  *      limit > 0
 389  */
 390
 391 unsigned int
 392 isc_mempool_getallocated(isc_mempool_t *mpctx);
 393 /*
 394  * Returns the number of items allocated from this pool.
 395  */
 396
 397 unsigned int
 398 isc_mempool_getfillcount(isc_mempool_t *mpctx);
 399 /*
 400  * Returns the number of items allocated as a block from the parent memory
 401  * context when the free list is empty.
 402  */
 403
 404 void
 405 isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
 406 /*
 407  * Sets the fillcount.
 408  *
 409  * Additional requirements:
 410  *      limit > 0
 411  */
 412
 413
 414 /*
 415  * Pseudo-private functions for use via macros.  Do not call directly.
 416  */
 417 void *
 418 isc__mem_get(isc_mem_t *, size_t _ISC_MEM_FLARG);
 419 void
 420 isc__mem_putanddetach(isc_mem_t **, void *,
 421                                       size_t _ISC_MEM_FLARG);
 422 void
 423 isc__mem_put(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
 424 void *
 425 isc__mem_allocate(isc_mem_t *, size_t _ISC_MEM_FLARG);
 426 void
 427 isc__mem_free(isc_mem_t *, void * _ISC_MEM_FLARG);
 428 char *
 429 isc__mem_strdup(isc_mem_t *, const char *_ISC_MEM_FLARG);
 430 void *
 431 isc__mempool_get(isc_mempool_t * _ISC_MEM_FLARG);
 432 void
 433 isc__mempool_put(isc_mempool_t *, void * _ISC_MEM_FLARG);
 434
 435 ISC_LANG_ENDDECLS
 436
 437 #endif /* ISC_MEM_H */