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

   1 /*
   2  * Copyright (C) 2004-2006, 2008  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1997-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or 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.59.18.11 2008/02/07 23:45:56 tbox Exp $ */
  19
  20 #ifndef ISC_MEM_H
  21 #define ISC_MEM_H 1
  22
  23 /*! \file */
  24
  25 #include <stdio.h>
  26
  27 #include <isc/lang.h>
  28 #include <isc/mutex.h>
  29 #include <isc/platform.h>
  30 #include <isc/types.h>
  31
  32 ISC_LANG_BEGINDECLS
  33
  34 #define ISC_MEM_LOWATER 0
  35 #define ISC_MEM_HIWATER 1
  36 typedef void (*isc_mem_water_t)(void *, int);
  37
  38 typedef void * (*isc_memalloc_t)(void *, size_t);
  39 typedef void (*isc_memfree_t)(void *, void *);
  40
  41 /*%
  42  * Define ISC_MEM_DEBUG=1 to make all functions that free memory
  43  * set the pointer being freed to NULL after being freed.
  44  * This is the default; set ISC_MEM_DEBUG=0 to disable it.
  45  */
  46 #ifndef ISC_MEM_DEBUG
  47 #define ISC_MEM_DEBUG 1
  48 #endif
  49
  50 /*%
  51  * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory
  52  * allocation and freeing by file and line number.
  53  */
  54 #ifndef ISC_MEM_TRACKLINES
  55 #define ISC_MEM_TRACKLINES 1
  56 #endif
  57
  58 /*%
  59  * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
  60  * the requested space.  This will increase the size of each allocation.
  61  */
  62 #ifndef ISC_MEM_CHECKOVERRUN
  63 #define ISC_MEM_CHECKOVERRUN 1
  64 #endif
  65
  66 /*%
  67  * Define ISC_MEM_FILL=1 to fill each block of memory returned to the system
  68  * with the byte string '0xbe'.  This helps track down uninitialized pointers
  69  * and the like.  On freeing memory, the space is filled with '0xde' for
  70  * the same reasons.
  71  */
  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 /*@{*/
  87 #define ISC_MEM_DEBUGTRACE              0x00000001U
  88 #define ISC_MEM_DEBUGRECORD             0x00000002U
  89 #define ISC_MEM_DEBUGUSAGE              0x00000004U
  90 #define ISC_MEM_DEBUGSIZE               0x00000008U
  91 #define ISC_MEM_DEBUGCTX                0x00000010U
  92 #define ISC_MEM_DEBUGALL                0x0000001FU
  93 /*!<
  94  * The variable isc_mem_debugging holds a set of flags for
  95  * turning certain memory debugging options on or off at
  96  * runtime.  Its is intialized to the value ISC_MEM_DEGBUGGING,
  97  * which is 0 by default but may be overridden at compile time.
  98  * The following flags can be specified:
  99  *
 100  * \li #ISC_MEM_DEBUGTRACE
 101  *      Log each allocation and free to isc_lctx.
 102  *
 103  * \li #ISC_MEM_DEBUGRECORD
 104  *      Remember each allocation, and match them up on free.
 105  *      Crash if a free doesn't match an allocation.
 106  *
 107  * \li #ISC_MEM_DEBUGUSAGE
 108  *      If a hi_water mark is set, print the maximium inuse memory
 109  *      every time it is raised once it exceeds the hi_water mark.
 110  *
 111  * \li #ISC_MEM_DEBUGSIZE
 112  *      Check the size argument being passed to isc_mem_put() matches
 113  *      that passed to isc_mem_get().
 114  *
 115  * \li #ISC_MEM_DEBUGCTX
 116  *      Check the mctx argument being passed to isc_mem_put() matches
 117  *      that passed to isc_mem_get().
 118  */
 119 /*@}*/
 120
 121 #if ISC_MEM_TRACKLINES
 122 #define _ISC_MEM_FILELINE       , __FILE__, __LINE__
 123 #define _ISC_MEM_FLARG          , const char *, int
 124 #else
 125 #define _ISC_MEM_FILELINE
 126 #define _ISC_MEM_FLARG
 127 #endif
 128
 129 /*!
 130  * Define ISC_MEM_USE_INTERNAL_MALLOC=1 to use the internal malloc()
 131  * implementation in preference to the system one.  The internal malloc()
 132  * is very space-efficient, and quite fast on uniprocessor systems.  It
 133  * performs poorly on multiprocessor machines.
 134  * JT: we can overcome the performance issue on multiprocessor machines
 135  * by carefully separating memory contexts.
 136  */
 137
 138 #ifndef ISC_MEM_USE_INTERNAL_MALLOC
 139 #define ISC_MEM_USE_INTERNAL_MALLOC 1
 140 #endif
 141
 142 /*
 143  * Flags for isc_mem_create2()calls.
 144  */
 145 #define ISC_MEMFLAG_NOLOCK      0x00000001       /* no lock is necessary */
 146 #define ISC_MEMFLAG_INTERNAL    0x00000002       /* use internal malloc */
 147 #if ISC_MEM_USE_INTERNAL_MALLOC
 148 #define ISC_MEMFLAG_DEFAULT     ISC_MEMFLAG_INTERNAL
 149 #else
 150 #define ISC_MEMFLAG_DEFAULT     0
 151 #endif
 152
 153
 154 #define isc_mem_get(c, s)       isc__mem_get((c), (s) _ISC_MEM_FILELINE)
 155 #define isc_mem_allocate(c, s)  isc__mem_allocate((c), (s) _ISC_MEM_FILELINE)
 156 #define isc_mem_strdup(c, p)    isc__mem_strdup((c), (p) _ISC_MEM_FILELINE)
 157 #define isc_mempool_get(c)      isc__mempool_get((c) _ISC_MEM_FILELINE)
 158
 159 /*%
 160  * isc_mem_putanddetach() is a convienence function for use where you
 161  * have a structure with an attached memory context.
 162  *
 163  * Given:
 164  *
 165  * \code
 166  * struct {
 167  *      ...
 168  *      isc_mem_t *mctx;
 169  *      ...
 170  * } *ptr;
 171  *
 172  * isc_mem_t *mctx;
 173  *
 174  * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
 175  * \endcode
 176  *
 177  * is the equivalent of:
 178  *
 179  * \code
 180  * mctx = NULL;
 181  * isc_mem_attach(ptr->mctx, &mctx);
 182  * isc_mem_detach(&ptr->mctx);
 183  * isc_mem_put(mctx, ptr, sizeof(*ptr));
 184  * isc_mem_detach(&mctx);
 185  * \endcode
 186  */
 187
 188 #if ISC_MEM_DEBUG
 189 #define isc_mem_put(c, p, s) \
 190         do { \
 191                 isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE); \
 192                 (p) = NULL; \
 193         } while (0)
 194 #define isc_mem_putanddetach(c, p, s) \
 195         do { \
 196                 isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE); \
 197                 (p) = NULL; \
 198         } while (0)
 199 #define isc_mem_free(c, p) \
 200         do { \
 201                 isc__mem_free((c), (p) _ISC_MEM_FILELINE); \
 202                 (p) = NULL; \
 203         } while (0)
 204 #define isc_mempool_put(c, p) \
 205         do { \
 206                 isc__mempool_put((c), (p) _ISC_MEM_FILELINE); \
 207                 (p) = NULL; \
 208         } while (0)
 209 #else
 210 #define isc_mem_put(c, p, s)    isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE)
 211 #define isc_mem_putanddetach(c, p, s) \
 212         isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE)
 213 #define isc_mem_free(c, p)      isc__mem_free((c), (p) _ISC_MEM_FILELINE)
 214 #define isc_mempool_put(c, p)   isc__mempool_put((c), (p) _ISC_MEM_FILELINE)
 215 #endif
 216
 217 /*@{*/
 218 isc_result_t
 219 isc_mem_create(size_t max_size, size_t target_size,
 220                isc_mem_t **mctxp);
 221
 222 isc_result_t
 223 isc_mem_create2(size_t max_size, size_t target_size,
 224                 isc_mem_t **mctxp, unsigned int flags);
 225
 226 isc_result_t
 227 isc_mem_createx(size_t max_size, size_t target_size,
 228                 isc_memalloc_t memalloc, isc_memfree_t memfree,
 229                 void *arg, isc_mem_t **mctxp);
 230
 231 isc_result_t
 232 isc_mem_createx2(size_t max_size, size_t target_size,
 233                  isc_memalloc_t memalloc, isc_memfree_t memfree,
 234                  void *arg, isc_mem_t **mctxp, unsigned int flags);
 235
 236 /*!<
 237  * \brief Create a memory context.
 238  *
 239  * 'max_size' and 'target_size' are tuning parameters.  When
 240  * ISC_MEMFLAG_INTERNAL is set, allocations smaller than 'max_size'
 241  * will be satisfied by getting blocks of size 'target_size' from the
 242  * system allocator and breaking them up into pieces; larger allocations
 243  * will use the system allocator directly. If 'max_size' and/or
 244  * 'target_size' are zero, default values will be * used.  When
 245  * ISC_MEMFLAG_INTERNAL is not set, 'target_size' is ignored.
 246  *
 247  * 'max_size' is also used to size the statistics arrays and the array
 248  * used to record active memory when ISC_MEM_DEBUGRECORD is set.  Settin
 249  * 'max_size' too low can have detrimental effects on performance.
 250  *
 251  * A memory context created using isc_mem_createx() will obtain
 252  * memory from the system by calling 'memalloc' and 'memfree',
 253  * passing them the argument 'arg'.  A memory context created
 254  * using isc_mem_create() will use the standard library malloc()
 255  * and free().
 256  *
 257  * If ISC_MEMFLAG_NOLOCK is set in 'flags', the corresponding memory context
 258  * will be accessed without locking.  The user who creates the context must
 259  * ensure there be no race.  Since this can be a source of bug, it is generally
 260  * inadvisable to use this flag unless the user is very sure about the race
 261  * condition and the access to the object is highly performance sensitive.
 262  *
 263  * Requires:
 264  * mctxp != NULL && *mctxp == NULL */
 265 /*@}*/
 266
 267 /*@{*/
 268 void
 269 isc_mem_attach(isc_mem_t *, isc_mem_t **);
 270 void
 271 isc_mem_detach(isc_mem_t **);
 272 /*!<
 273  * \brief Attach to / detach from a memory context.
 274  *
 275  * This is intended for applications that use multiple memory contexts
 276  * in such a way that it is not obvious when the last allocations from
 277  * a given context has been freed and destroying the context is safe.
 278  *
 279  * Most applications do not need to call these functions as they can
 280  * simply create a single memory context at the beginning of main()
 281  * and destroy it at the end of main(), thereby guaranteeing that it
 282  * is not destroyed while there are outstanding allocations.
 283  */
 284 /*@}*/
 285
 286 void
 287 isc_mem_destroy(isc_mem_t **);
 288 /*%<
 289  * Destroy a memory context.
 290  */
 291
 292 isc_result_t
 293 isc_mem_ondestroy(isc_mem_t *ctx,
 294                   isc_task_t *task,
 295                   isc_event_t **event);
 296 /*%<
 297  * Request to be notified with an event when a memory context has
 298  * been successfully destroyed.
 299  */
 300
 301 void
 302 isc_mem_stats(isc_mem_t *mctx, FILE *out);
 303 /*%<
 304  * Print memory usage statistics for 'mctx' on the stream 'out'.
 305  */
 306
 307 void
 308 isc_mem_setdestroycheck(isc_mem_t *mctx,
 309                         isc_boolean_t on);
 310 /*%<
 311  * If 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
 312  * destroyed and abort the program if any are present.
 313  */
 314
 315 /*@{*/
 316 void
 317 isc_mem_setquota(isc_mem_t *, size_t);
 318 size_t
 319 isc_mem_getquota(isc_mem_t *);
 320 /*%<
 321  * Set/get the memory quota of 'mctx'.  This is a hard limit
 322  * on the amount of memory that may be allocated from mctx;
 323  * if it is exceeded, allocations will fail.
 324  */
 325 /*@}*/
 326
 327 size_t
 328 isc_mem_inuse(isc_mem_t *mctx);
 329 /*%<
 330  * Get an estimate of the number of memory in use in 'mctx', in bytes.
 331  * This includes quantization overhead, but does not include memory
 332  * allocated from the system but not yet used.
 333  */
 334
 335 void
 336 isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
 337                  size_t hiwater, size_t lowater);
 338 /*%<
 339  * Set high and low water marks for this memory context.
 340  *
 341  * When the memory usage of 'mctx' exceeds 'hiwater',
 342  * '(water)(water_arg, #ISC_MEM_HIWATER)' will be called.  'water' needs to
 343  * call isc_mem_waterack() with #ISC_MEM_HIWATER to acknowlege the state
 344  * change.  'water' may be called multiple times.
 345  *
 346  * When the usage drops below 'lowater', 'water' will again be called, this
 347  * time with #ISC_MEM_LOWATER.  'water' need to calls isc_mem_waterack() with
 348  * #ISC_MEM_LOWATER to acknowlege the change.
 349  *
 350  *      static void
 351  *      water(void *arg, int mark) {
 352  *              struct foo *foo = arg;
 353  *
 354  *              LOCK(&foo->marklock);
 355  *              if (foo->mark != mark) {
 356  *                      foo->mark = mark;
 357  *                      ....
 358  *                      isc_mem_waterack(foo->mctx, mark);
 359  *              }
 360  *              UNLOCK(&foo->marklock);
 361  *      }
 362  * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
 363  * ignored and the state is reset.
 364  *
 365  * Requires:
 366  *
 367  *      'water' is not NULL.
 368  *      hi_water >= lo_water
 369  */
 370
 371 void
 372 isc_mem_waterack(isc_mem_t *ctx, int mark);
 373 /*%<
 374  * Called to acknowledge changes in signalled by calls to 'water'.
 375  */
 376
 377 void
 378 isc_mem_printactive(isc_mem_t *mctx, FILE *file);
 379 /*%<
 380  * Print to 'file' all active memory in 'mctx'.
 381  *
 382  * Requires ISC_MEM_DEBUGRECORD to have been set.
 383  */
 384
 385 void
 386 isc_mem_printallactive(FILE *file);
 387 /*%<
 388  * Print to 'file' all active memory in all contexts.
 389  *
 390  * Requires ISC_MEM_DEBUGRECORD to have been set.
 391  */
 392
 393 void
 394 isc_mem_checkdestroyed(FILE *file);
 395 /*%<
 396  * Check that all memory contexts have been destroyed.
 397  * Prints out those that have not been.
 398  * Fatally fails if there are still active contexts.
 399  */
 400
 401 /*
 402  * Memory pools
 403  */
 404
 405 isc_result_t
 406 isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
 407 /*%<
 408  * Create a memory pool.
 409  *
 410  * Requires:
 411  *\li   mctx is a valid memory context.
 412  *\li   size > 0
 413  *\li   mpctxp != NULL and *mpctxp == NULL
 414  *
 415  * Defaults:
 416  *\li   maxalloc = UINT_MAX
 417  *\li   freemax = 1
 418  *\li   fillcount = 1
 419  *
 420  * Returns:
 421  *\li   #ISC_R_NOMEMORY         -- not enough memory to create pool
 422  *\li   #ISC_R_SUCCESS          -- all is well.
 423  */
 424
 425 void
 426 isc_mempool_destroy(isc_mempool_t **mpctxp);
 427 /*%<
 428  * Destroy a memory pool.
 429  *
 430  * Requires:
 431  *\li   mpctxp != NULL && *mpctxp is a valid pool.
 432  *\li   The pool has no un"put" allocations outstanding
 433  */
 434
 435 void
 436 isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
 437 /*%<
 438  * Associate a name with a memory pool.  At most 15 characters may be used.
 439  *
 440  * Requires:
 441  *\li   mpctx is a valid pool.
 442  *\li   name != NULL;
 443  */
 444
 445 void
 446 isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
 447 /*%<
 448  * Associate a lock with this memory pool.
 449  *
 450  * This lock is used when getting or putting items using this memory pool,
 451  * and it is also used to set or get internal state via the isc_mempool_get*()
 452  * and isc_mempool_set*() set of functions.
 453  *
 454  * Mutiple pools can each share a single lock.  For instance, if "manager"
 455  * type object contained pools for various sizes of events, and each of
 456  * these pools used a common lock.  Note that this lock must NEVER be used
 457  * by other than mempool routines once it is given to a pool, since that can
 458  * easily cause double locking.
 459  *
 460  * Requires:
 461  *
 462  *\li   mpctpx is a valid pool.
 463  *
 464  *\li   lock != NULL.
 465  *
 466  *\li   No previous lock is assigned to this pool.
 467  *
 468  *\li   The lock is initialized before calling this function via the normal
 469  *      means of doing that.
 470  */
 471
 472 /*
 473  * The following functions get/set various parameters.  Note that due to
 474  * the unlocked nature of pools these are potentially random values unless
 475  * the imposed externally provided locking protocols are followed.
 476  *
 477  * Also note that the quota limits will not always take immediate effect.
 478  * For instance, setting "maxalloc" to a number smaller than the currently
 479  * allocated count is permitted.  New allocations will be refused until
 480  * the count drops below this threshold.
 481  *
 482  * All functions require (in addition to other requirements):
 483  *      mpctx is a valid memory pool
 484  */
 485
 486 unsigned int
 487 isc_mempool_getfreemax(isc_mempool_t *mpctx);
 488 /*%<
 489  * Returns the maximum allowed size of the free list.
 490  */
 491
 492 void
 493 isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
 494 /*%<
 495  * Sets the maximum allowed size of the free list.
 496  */
 497
 498 unsigned int
 499 isc_mempool_getfreecount(isc_mempool_t *mpctx);
 500 /*%<
 501  * Returns current size of the free list.
 502  */
 503
 504 unsigned int
 505 isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
 506 /*!<
 507  * Returns the maximum allowed number of allocations.
 508  */
 509
 510 void
 511 isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
 512 /*%<
 513  * Sets the maximum allowed number of allocations.
 514  *
 515  * Additional requirements:
 516  *\li   limit > 0
 517  */
 518
 519 unsigned int
 520 isc_mempool_getallocated(isc_mempool_t *mpctx);
 521 /*%<
 522  * Returns the number of items allocated from this pool.
 523  */
 524
 525 unsigned int
 526 isc_mempool_getfillcount(isc_mempool_t *mpctx);
 527 /*%<
 528  * Returns the number of items allocated as a block from the parent memory
 529  * context when the free list is empty.
 530  */
 531
 532 void
 533 isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
 534 /*%<
 535  * Sets the fillcount.
 536  *
 537  * Additional requirements:
 538  *\li   limit > 0
 539  */
 540
 541
 542 /*
 543  * Pseudo-private functions for use via macros.  Do not call directly.
 544  */
 545 void *
 546 isc__mem_get(isc_mem_t *, size_t _ISC_MEM_FLARG);
 547 void
 548 isc__mem_putanddetach(isc_mem_t **, void *,
 549                                       size_t _ISC_MEM_FLARG);
 550 void
 551 isc__mem_put(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
 552 void *
 553 isc__mem_allocate(isc_mem_t *, size_t _ISC_MEM_FLARG);
 554 void
 555 isc__mem_free(isc_mem_t *, void * _ISC_MEM_FLARG);
 556 char *
 557 isc__mem_strdup(isc_mem_t *, const char *_ISC_MEM_FLARG);
 558 void *
 559 isc__mempool_get(isc_mempool_t * _ISC_MEM_FLARG);
 560 void
 561 isc__mempool_put(isc_mempool_t *, void * _ISC_MEM_FLARG);
 562
 563 ISC_LANG_ENDDECLS
 564
 565 #endif /* ISC_MEM_H */