2 * Copyright (C) 2004-2010, 2012 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1997-2001 Internet Software Consortium.
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.
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.
23 /*! \file isc/mem.h */
28 #include <isc/mutex.h>
29 #include <isc/platform.h>
30 #include <isc/types.h>
35 #define ISC_MEM_LOWATER 0
36 #define ISC_MEM_HIWATER 1
37 typedef void (*isc_mem_water_t)(void *, int);
39 typedef void * (*isc_memalloc_t)(void *, size_t);
40 typedef void (*isc_memfree_t)(void *, void *);
43 * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory
44 * allocation and freeing by file and line number.
46 #ifndef ISC_MEM_TRACKLINES
47 #define ISC_MEM_TRACKLINES 1
51 * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
52 * the requested space. This will increase the size of each allocation.
54 #ifndef ISC_MEM_CHECKOVERRUN
55 #define ISC_MEM_CHECKOVERRUN 1
59 * Define ISC_MEM_FILL=1 to fill each block of memory returned to the system
60 * with the byte string '0xbe'. This helps track down uninitialized pointers
61 * and the like. On freeing memory, the space is filled with '0xde' for
65 #define ISC_MEM_FILL 1
69 * Define ISC_MEMPOOL_NAMES=1 to make memory pools store a symbolic
70 * name so that the leaking pool can be more readily identified in
71 * case of a memory leak.
73 #ifndef ISC_MEMPOOL_NAMES
74 #define ISC_MEMPOOL_NAMES 1
77 LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging;
79 #define ISC_MEM_DEBUGTRACE 0x00000001U
80 #define ISC_MEM_DEBUGRECORD 0x00000002U
81 #define ISC_MEM_DEBUGUSAGE 0x00000004U
82 #define ISC_MEM_DEBUGSIZE 0x00000008U
83 #define ISC_MEM_DEBUGCTX 0x00000010U
84 #define ISC_MEM_DEBUGALL 0x0000001FU
86 * The variable isc_mem_debugging holds a set of flags for
87 * turning certain memory debugging options on or off at
88 * runtime. It is initialized to the value ISC_MEM_DEGBUGGING,
89 * which is 0 by default but may be overridden at compile time.
90 * The following flags can be specified:
92 * \li #ISC_MEM_DEBUGTRACE
93 * Log each allocation and free to isc_lctx.
95 * \li #ISC_MEM_DEBUGRECORD
96 * Remember each allocation, and match them up on free.
97 * Crash if a free doesn't match an allocation.
99 * \li #ISC_MEM_DEBUGUSAGE
100 * If a hi_water mark is set, print the maximum inuse memory
101 * every time it is raised once it exceeds the hi_water mark.
103 * \li #ISC_MEM_DEBUGSIZE
104 * Check the size argument being passed to isc_mem_put() matches
105 * that passed to isc_mem_get().
107 * \li #ISC_MEM_DEBUGCTX
108 * Check the mctx argument being passed to isc_mem_put() matches
109 * that passed to isc_mem_get().
113 #if ISC_MEM_TRACKLINES
114 #define _ISC_MEM_FILELINE , __FILE__, __LINE__
115 #define _ISC_MEM_FLARG , const char *, unsigned int
117 #define _ISC_MEM_FILELINE
118 #define _ISC_MEM_FLARG
122 * Define ISC_MEM_USE_INTERNAL_MALLOC=1 to use the internal malloc()
123 * implementation in preference to the system one. The internal malloc()
124 * is very space-efficient, and quite fast on uniprocessor systems. It
125 * performs poorly on multiprocessor machines.
126 * JT: we can overcome the performance issue on multiprocessor machines
127 * by carefully separating memory contexts.
130 #ifndef ISC_MEM_USE_INTERNAL_MALLOC
131 #define ISC_MEM_USE_INTERNAL_MALLOC 1
135 * Flags for isc_mem_create2()calls.
137 #define ISC_MEMFLAG_NOLOCK 0x00000001 /* no lock is necessary */
138 #define ISC_MEMFLAG_INTERNAL 0x00000002 /* use internal malloc */
139 #if ISC_MEM_USE_INTERNAL_MALLOC
140 #define ISC_MEMFLAG_DEFAULT ISC_MEMFLAG_INTERNAL
142 #define ISC_MEMFLAG_DEFAULT 0
147 * We use either isc___mem (three underscores) or isc__mem (two) depending on
148 * whether it's for BIND9's internal purpose (with -DBIND9) or generic export
149 * library. This condition is generally handled in isc/namespace.h, but for
150 * Windows it doesn't work if it involves multiple times of macro expansion
151 * (such as isc_mem to isc__mem then to isc___mem). The following definitions
152 * are used to work around this portability issue. Right now, we don't support
153 * the export library for Windows, so we always use the three-underscore
157 #define ISCMEMFUNC(sfx) isc___mem_ ## sfx
158 #define ISCMEMPOOLFUNC(sfx) isc___mempool_ ## sfx
160 #define ISCMEMFUNC(sfx) isc__mem_ ## sfx
161 #define ISCMEMPOOLFUNC(sfx) isc__mempool_ ## sfx
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)
171 * isc_mem_putanddetach() is a convenience function for use where you
172 * have a structure with an attached memory context.
185 * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
188 * is the equivalent of:
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);
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, isc_boolean_t 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 isc_boolean_t (*isovermem)(isc_mem_t *mctx);
219 isc_result_t (*mpcreate)(isc_mem_t *mctx, size_t size,
220 isc_mempool_t **mpctxp);
223 typedef struct isc_mempoolmethods {
224 void (*destroy)(isc_mempool_t **mpctxp);
225 void *(*get)(isc_mempool_t *mpctx _ISC_MEM_FLARG);
226 void (*put)(isc_mempool_t *mpctx, void *mem _ISC_MEM_FLARG);
227 unsigned int (*getallocated)(isc_mempool_t *mpctx);
228 void (*setmaxalloc)(isc_mempool_t *mpctx, unsigned int limit);
229 void (*setfreemax)(isc_mempool_t *mpctx, unsigned int limit);
230 void (*setname)(isc_mempool_t *mpctx, const char *name);
231 void (*associatelock)(isc_mempool_t *mpctx, isc_mutex_t *lock);
232 void (*setfillcount)(isc_mempool_t *mpctx, unsigned int limit);
233 } isc_mempoolmethods_t;
236 * This structure is actually just the common prefix of a memory context
237 * implementation's version of an isc_mem_t.
239 * Direct use of this structure by clients is forbidden. mctx implementations
240 * may change the structure. 'magic' must be ISCAPI_MCTX_MAGIC for any of the
241 * isc_mem_ routines to work. mctx implementations must maintain all mctx
245 unsigned int impmagic;
247 isc_memmethods_t *methods;
250 #define ISCAPI_MCTX_MAGIC ISC_MAGIC('A','m','c','x')
251 #define ISCAPI_MCTX_VALID(m) ((m) != NULL && \
252 (m)->magic == ISCAPI_MCTX_MAGIC)
255 * This is the common prefix of a memory pool context. The same note as
256 * that for the mem structure applies.
259 unsigned int impmagic;
261 isc_mempoolmethods_t *methods;
264 #define ISCAPI_MPOOL_MAGIC ISC_MAGIC('A','m','p','l')
265 #define ISCAPI_MPOOL_VALID(mp) ((mp) != NULL && \
266 (mp)->magic == ISCAPI_MPOOL_MAGIC)
268 #define isc_mem_put(c, p, s) \
270 ISCMEMFUNC(put)((c), (p), (s) _ISC_MEM_FILELINE); \
273 #define isc_mem_putanddetach(c, p, s) \
275 ISCMEMFUNC(putanddetach)((c), (p), (s) _ISC_MEM_FILELINE); \
278 #define isc_mem_free(c, p) \
280 ISCMEMFUNC(free)((c), (p) _ISC_MEM_FILELINE); \
283 #define isc_mempool_put(c, p) \
285 ISCMEMPOOLFUNC(put)((c), (p) _ISC_MEM_FILELINE); \
291 isc_mem_create(size_t max_size, size_t target_size,
295 isc_mem_create2(size_t max_size, size_t target_size,
296 isc_mem_t **mctxp, unsigned int flags);
299 isc_mem_createx(size_t max_size, size_t target_size,
300 isc_memalloc_t memalloc, isc_memfree_t memfree,
301 void *arg, isc_mem_t **mctxp);
304 isc_mem_createx2(size_t max_size, size_t target_size,
305 isc_memalloc_t memalloc, isc_memfree_t memfree,
306 void *arg, isc_mem_t **mctxp, unsigned int flags);
309 * \brief Create a memory context.
311 * 'max_size' and 'target_size' are tuning parameters. When
312 * ISC_MEMFLAG_INTERNAL is set, allocations smaller than 'max_size'
313 * will be satisfied by getting blocks of size 'target_size' from the
314 * system allocator and breaking them up into pieces; larger allocations
315 * will use the system allocator directly. If 'max_size' and/or
316 * 'target_size' are zero, default values will be * used. When
317 * ISC_MEMFLAG_INTERNAL is not set, 'target_size' is ignored.
319 * 'max_size' is also used to size the statistics arrays and the array
320 * used to record active memory when ISC_MEM_DEBUGRECORD is set. Settin
321 * 'max_size' too low can have detrimental effects on performance.
323 * A memory context created using isc_mem_createx() will obtain
324 * memory from the system by calling 'memalloc' and 'memfree',
325 * passing them the argument 'arg'. A memory context created
326 * using isc_mem_create() will use the standard library malloc()
329 * If ISC_MEMFLAG_NOLOCK is set in 'flags', the corresponding memory context
330 * will be accessed without locking. The user who creates the context must
331 * ensure there be no race. Since this can be a source of bug, it is generally
332 * inadvisable to use this flag unless the user is very sure about the race
333 * condition and the access to the object is highly performance sensitive.
336 * mctxp != NULL && *mctxp == NULL */
341 isc_mem_attach(isc_mem_t *, isc_mem_t **);
343 isc_mem_detach(isc_mem_t **);
345 * \brief Attach to / detach from a memory context.
347 * This is intended for applications that use multiple memory contexts
348 * in such a way that it is not obvious when the last allocations from
349 * a given context has been freed and destroying the context is safe.
351 * Most applications do not need to call these functions as they can
352 * simply create a single memory context at the beginning of main()
353 * and destroy it at the end of main(), thereby guaranteeing that it
354 * is not destroyed while there are outstanding allocations.
359 isc_mem_destroy(isc_mem_t **);
361 * Destroy a memory context.
365 isc_mem_ondestroy(isc_mem_t *ctx,
367 isc_event_t **event);
369 * Request to be notified with an event when a memory context has
370 * been successfully destroyed.
374 isc_mem_stats(isc_mem_t *mctx, FILE *out);
376 * Print memory usage statistics for 'mctx' on the stream 'out'.
380 isc_mem_setdestroycheck(isc_mem_t *mctx,
383 * If 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
384 * destroyed and abort the program if any are present.
389 isc_mem_setquota(isc_mem_t *, size_t);
391 isc_mem_getquota(isc_mem_t *);
393 * Set/get the memory quota of 'mctx'. This is a hard limit
394 * on the amount of memory that may be allocated from mctx;
395 * if it is exceeded, allocations will fail.
400 isc_mem_inuse(isc_mem_t *mctx);
402 * Get an estimate of the number of memory in use in 'mctx', in bytes.
403 * This includes quantization overhead, but does not include memory
404 * allocated from the system but not yet used.
408 isc_mem_isovermem(isc_mem_t *mctx);
410 * Return true iff the memory context is in "over memory" state, i.e.,
411 * a hiwater mark has been set and the used amount of memory has exceeds
416 isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
417 size_t hiwater, size_t lowater);
419 * Set high and low water marks for this memory context.
421 * When the memory usage of 'mctx' exceeds 'hiwater',
422 * '(water)(water_arg, #ISC_MEM_HIWATER)' will be called. 'water' needs to
423 * call isc_mem_waterack() with #ISC_MEM_HIWATER to acknowledge the state
424 * change. 'water' may be called multiple times.
426 * When the usage drops below 'lowater', 'water' will again be called, this
427 * time with #ISC_MEM_LOWATER. 'water' need to calls isc_mem_waterack() with
428 * #ISC_MEM_LOWATER to acknowledge the change.
431 * water(void *arg, int mark) {
432 * struct foo *foo = arg;
434 * LOCK(&foo->marklock);
435 * if (foo->mark != mark) {
438 * isc_mem_waterack(foo->mctx, mark);
440 * UNLOCK(&foo->marklock);
443 * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
444 * ignored and the state is reset.
448 * 'water' is not NULL.
449 * hi_water >= lo_water
453 isc_mem_waterack(isc_mem_t *ctx, int mark);
455 * Called to acknowledge changes in signaled by calls to 'water'.
459 isc_mem_printactive(isc_mem_t *mctx, FILE *file);
461 * Print to 'file' all active memory in 'mctx'.
463 * Requires ISC_MEM_DEBUGRECORD to have been set.
467 isc_mem_printallactive(FILE *file);
469 * Print to 'file' all active memory in all contexts.
471 * Requires ISC_MEM_DEBUGRECORD to have been set.
475 isc_mem_checkdestroyed(FILE *file);
477 * Check that all memory contexts have been destroyed.
478 * Prints out those that have not been.
479 * Fatally fails if there are still active contexts.
483 isc_mem_references(isc_mem_t *ctx);
485 * Return the current reference count.
489 isc_mem_setname(isc_mem_t *ctx, const char *name, void *tag);
495 *\li Only the first 15 characters of 'name' will be copied.
497 *\li 'tag' is for debugging purposes only.
501 *\li 'ctx' is a valid ctx.
505 isc_mem_getname(isc_mem_t *ctx);
507 * Get the name of 'ctx', as previously set using isc_mem_setname().
510 *\li 'ctx' is a valid ctx.
513 *\li A non-NULL pointer to a null-terminated string.
514 * If the ctx has not been named, the string is
519 isc_mem_gettag(isc_mem_t *ctx);
521 * Get the tag value for 'task', as previously set using isc_mem_setname().
524 *\li 'ctx' is a valid ctx.
527 *\li This function is for debugging purposes only.
530 *\li 'ctx' is a valid task.
535 isc_mem_renderxml(xmlTextWriterPtr writer);
537 * Render all contexts' statistics and status in XML for writer.
539 #endif /* HAVE_LIBXML2 */
546 isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
548 * Create a memory pool.
551 *\li mctx is a valid memory context.
553 *\li mpctxp != NULL and *mpctxp == NULL
556 *\li maxalloc = UINT_MAX
561 *\li #ISC_R_NOMEMORY -- not enough memory to create pool
562 *\li #ISC_R_SUCCESS -- all is well.
566 isc_mempool_destroy(isc_mempool_t **mpctxp);
568 * Destroy a memory pool.
571 *\li mpctxp != NULL && *mpctxp is a valid pool.
572 *\li The pool has no un"put" allocations outstanding
576 isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
578 * Associate a name with a memory pool. At most 15 characters may be used.
581 *\li mpctx is a valid pool.
586 isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
588 * Associate a lock with this memory pool.
590 * This lock is used when getting or putting items using this memory pool,
591 * and it is also used to set or get internal state via the isc_mempool_get*()
592 * and isc_mempool_set*() set of functions.
594 * Multiple pools can each share a single lock. For instance, if "manager"
595 * type object contained pools for various sizes of events, and each of
596 * these pools used a common lock. Note that this lock must NEVER be used
597 * by other than mempool routines once it is given to a pool, since that can
598 * easily cause double locking.
602 *\li mpctpx is a valid pool.
606 *\li No previous lock is assigned to this pool.
608 *\li The lock is initialized before calling this function via the normal
609 * means of doing that.
613 * The following functions get/set various parameters. Note that due to
614 * the unlocked nature of pools these are potentially random values unless
615 * the imposed externally provided locking protocols are followed.
617 * Also note that the quota limits will not always take immediate effect.
618 * For instance, setting "maxalloc" to a number smaller than the currently
619 * allocated count is permitted. New allocations will be refused until
620 * the count drops below this threshold.
622 * All functions require (in addition to other requirements):
623 * mpctx is a valid memory pool
627 isc_mempool_getfreemax(isc_mempool_t *mpctx);
629 * Returns the maximum allowed size of the free list.
633 isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
635 * Sets the maximum allowed size of the free list.
639 isc_mempool_getfreecount(isc_mempool_t *mpctx);
641 * Returns current size of the free list.
645 isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
647 * Returns the maximum allowed number of allocations.
651 isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
653 * Sets the maximum allowed number of allocations.
655 * Additional requirements:
660 isc_mempool_getallocated(isc_mempool_t *mpctx);
662 * Returns the number of items allocated from this pool.
666 isc_mempool_getfillcount(isc_mempool_t *mpctx);
668 * Returns the number of items allocated as a block from the parent memory
669 * context when the free list is empty.
673 isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
675 * Sets the fillcount.
677 * Additional requirements:
683 * Pseudo-private functions for use via macros. Do not call directly.
686 ISCMEMFUNC(get)(isc_mem_t *, size_t _ISC_MEM_FLARG);
688 ISCMEMFUNC(putanddetach)(isc_mem_t **, void *, size_t _ISC_MEM_FLARG);
690 ISCMEMFUNC(put)(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
692 ISCMEMFUNC(allocate)(isc_mem_t *, size_t _ISC_MEM_FLARG);
694 ISCMEMFUNC(reallocate)(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
696 ISCMEMFUNC(free)(isc_mem_t *, void * _ISC_MEM_FLARG);
698 ISCMEMFUNC(strdup)(isc_mem_t *, const char *_ISC_MEM_FLARG);
700 ISCMEMPOOLFUNC(get)(isc_mempool_t * _ISC_MEM_FLARG);
702 ISCMEMPOOLFUNC(put)(isc_mempool_t *, void * _ISC_MEM_FLARG);
704 #ifdef USE_MEMIMPREGISTER
707 * See isc_mem_create2() above.
710 (*isc_memcreatefunc_t)(size_t init_max_size, size_t target_size,
711 isc_mem_t **ctxp, unsigned int flags);
714 isc_mem_register(isc_memcreatefunc_t createfunc);
716 * Register a new memory management implementation and add it to the list of
717 * supported implementations. This function must be called when a different
718 * memory management library is used than the one contained in the ISC library.
722 isc__mem_register(void);
724 * A short cut function that specifies the memory management module in the ISC
725 * library for isc_mem_register(). An application that uses the ISC library
726 * usually do not have to care about this function: it would call
727 * isc_lib_register(), which internally calls this function.
729 #endif /* USE_MEMIMPREGISTER */
733 #endif /* ISC_MEM_H */