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