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