2 * Copyright (C) 2004-2006, 2008 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.
18 /* $Id: mem.h,v 1.59.18.11 2008/02/07 23:45:56 tbox Exp $ */
28 #include <isc/mutex.h>
29 #include <isc/platform.h>
30 #include <isc/types.h>
34 #define ISC_MEM_LOWATER 0
35 #define ISC_MEM_HIWATER 1
36 typedef void (*isc_mem_water_t)(void *, int);
38 typedef void * (*isc_memalloc_t)(void *, size_t);
39 typedef void (*isc_memfree_t)(void *, void *);
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.
47 #define ISC_MEM_DEBUG 1
51 * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory
52 * allocation and freeing by file and line number.
54 #ifndef ISC_MEM_TRACKLINES
55 #define ISC_MEM_TRACKLINES 1
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.
62 #ifndef ISC_MEM_CHECKOVERRUN
63 #define ISC_MEM_CHECKOVERRUN 1
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
73 #define ISC_MEM_FILL 1
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.
81 #ifndef ISC_MEMPOOL_NAMES
82 #define ISC_MEMPOOL_NAMES 1
85 LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging;
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
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:
100 * \li #ISC_MEM_DEBUGTRACE
101 * Log each allocation and free to isc_lctx.
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.
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.
111 * \li #ISC_MEM_DEBUGSIZE
112 * Check the size argument being passed to isc_mem_put() matches
113 * that passed to isc_mem_get().
115 * \li #ISC_MEM_DEBUGCTX
116 * Check the mctx argument being passed to isc_mem_put() matches
117 * that passed to isc_mem_get().
121 #if ISC_MEM_TRACKLINES
122 #define _ISC_MEM_FILELINE , __FILE__, __LINE__
123 #define _ISC_MEM_FLARG , const char *, int
125 #define _ISC_MEM_FILELINE
126 #define _ISC_MEM_FLARG
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.
138 #ifndef ISC_MEM_USE_INTERNAL_MALLOC
139 #define ISC_MEM_USE_INTERNAL_MALLOC 1
143 * Flags for isc_mem_create2()calls.
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
150 #define ISC_MEMFLAG_DEFAULT 0
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)
160 * isc_mem_putanddetach() is a convienence function for use where you
161 * have a structure with an attached memory context.
174 * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
177 * is the equivalent of:
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);
189 #define isc_mem_put(c, p, s) \
191 isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE); \
194 #define isc_mem_putanddetach(c, p, s) \
196 isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE); \
199 #define isc_mem_free(c, p) \
201 isc__mem_free((c), (p) _ISC_MEM_FILELINE); \
204 #define isc_mempool_put(c, p) \
206 isc__mempool_put((c), (p) _ISC_MEM_FILELINE); \
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)
219 isc_mem_create(size_t max_size, size_t target_size,
223 isc_mem_create2(size_t max_size, size_t target_size,
224 isc_mem_t **mctxp, unsigned int flags);
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);
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);
237 * \brief Create a memory context.
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.
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.
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()
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.
264 * mctxp != NULL && *mctxp == NULL */
269 isc_mem_attach(isc_mem_t *, isc_mem_t **);
271 isc_mem_detach(isc_mem_t **);
273 * \brief Attach to / detach from a memory context.
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.
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.
287 isc_mem_destroy(isc_mem_t **);
289 * Destroy a memory context.
293 isc_mem_ondestroy(isc_mem_t *ctx,
295 isc_event_t **event);
297 * Request to be notified with an event when a memory context has
298 * been successfully destroyed.
302 isc_mem_stats(isc_mem_t *mctx, FILE *out);
304 * Print memory usage statistics for 'mctx' on the stream 'out'.
308 isc_mem_setdestroycheck(isc_mem_t *mctx,
311 * If 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
312 * destroyed and abort the program if any are present.
317 isc_mem_setquota(isc_mem_t *, size_t);
319 isc_mem_getquota(isc_mem_t *);
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.
328 isc_mem_inuse(isc_mem_t *mctx);
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.
336 isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
337 size_t hiwater, size_t lowater);
339 * Set high and low water marks for this memory context.
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.
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.
351 * water(void *arg, int mark) {
352 * struct foo *foo = arg;
354 * LOCK(&foo->marklock);
355 * if (foo->mark != mark) {
358 * isc_mem_waterack(foo->mctx, mark);
360 * UNLOCK(&foo->marklock);
362 * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
363 * ignored and the state is reset.
367 * 'water' is not NULL.
368 * hi_water >= lo_water
372 isc_mem_waterack(isc_mem_t *ctx, int mark);
374 * Called to acknowledge changes in signalled by calls to 'water'.
378 isc_mem_printactive(isc_mem_t *mctx, FILE *file);
380 * Print to 'file' all active memory in 'mctx'.
382 * Requires ISC_MEM_DEBUGRECORD to have been set.
386 isc_mem_printallactive(FILE *file);
388 * Print to 'file' all active memory in all contexts.
390 * Requires ISC_MEM_DEBUGRECORD to have been set.
394 isc_mem_checkdestroyed(FILE *file);
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.
406 isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
408 * Create a memory pool.
411 *\li mctx is a valid memory context.
413 *\li mpctxp != NULL and *mpctxp == NULL
416 *\li maxalloc = UINT_MAX
421 *\li #ISC_R_NOMEMORY -- not enough memory to create pool
422 *\li #ISC_R_SUCCESS -- all is well.
426 isc_mempool_destroy(isc_mempool_t **mpctxp);
428 * Destroy a memory pool.
431 *\li mpctxp != NULL && *mpctxp is a valid pool.
432 *\li The pool has no un"put" allocations outstanding
436 isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
438 * Associate a name with a memory pool. At most 15 characters may be used.
441 *\li mpctx is a valid pool.
446 isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
448 * Associate a lock with this memory pool.
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.
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.
462 *\li mpctpx is a valid pool.
466 *\li No previous lock is assigned to this pool.
468 *\li The lock is initialized before calling this function via the normal
469 * means of doing that.
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.
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.
482 * All functions require (in addition to other requirements):
483 * mpctx is a valid memory pool
487 isc_mempool_getfreemax(isc_mempool_t *mpctx);
489 * Returns the maximum allowed size of the free list.
493 isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
495 * Sets the maximum allowed size of the free list.
499 isc_mempool_getfreecount(isc_mempool_t *mpctx);
501 * Returns current size of the free list.
505 isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
507 * Returns the maximum allowed number of allocations.
511 isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
513 * Sets the maximum allowed number of allocations.
515 * Additional requirements:
520 isc_mempool_getallocated(isc_mempool_t *mpctx);
522 * Returns the number of items allocated from this pool.
526 isc_mempool_getfillcount(isc_mempool_t *mpctx);
528 * Returns the number of items allocated as a block from the parent memory
529 * context when the free list is empty.
533 isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
535 * Sets the fillcount.
537 * Additional requirements:
543 * Pseudo-private functions for use via macros. Do not call directly.
546 isc__mem_get(isc_mem_t *, size_t _ISC_MEM_FLARG);
548 isc__mem_putanddetach(isc_mem_t **, void *,
549 size_t _ISC_MEM_FLARG);
551 isc__mem_put(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
553 isc__mem_allocate(isc_mem_t *, size_t _ISC_MEM_FLARG);
555 isc__mem_free(isc_mem_t *, void * _ISC_MEM_FLARG);
557 isc__mem_strdup(isc_mem_t *, const char *_ISC_MEM_FLARG);
559 isc__mempool_get(isc_mempool_t * _ISC_MEM_FLARG);
561 isc__mempool_put(isc_mempool_t *, void * _ISC_MEM_FLARG);
565 #endif /* ISC_MEM_H */