2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1997-2001 Internet Software Consortium.
5 * Permission to use, copy, modify, and 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.54.2.1 2004/03/09 06:11:58 marka Exp $ */
26 #include <isc/mutex.h>
27 #include <isc/platform.h>
28 #include <isc/types.h>
32 #define ISC_MEM_LOWATER 0
33 #define ISC_MEM_HIWATER 1
34 typedef void (*isc_mem_water_t
)(void *, int);
36 typedef void * (*isc_memalloc_t
)(void *, size_t);
37 typedef void (*isc_memfree_t
)(void *, void *);
40 * ISC_MEM_DEBUG is enabled by default; set ISC_MEM_DEBUG=0 to disable it.
43 #define ISC_MEM_DEBUG 1
47 * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory allocation
48 * and freeing by file and line number.
50 #ifndef ISC_MEM_TRACKLINES
51 #define ISC_MEM_TRACKLINES 0
55 * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
56 * the requested space. This will increase the size of each allocation.
58 #ifndef ISC_MEM_CHECKOVERRUN
59 #define ISC_MEM_CHECKOVERRUN 0
63 * Define ISC_MEM_FILL to fill each block of memory returned to the system
64 * with the byte string '0xbe'. This helps track down uninitialized pointers
65 * and the like. On freeing memory, the space is filled with '0xde' for
69 #define ISC_MEM_FILL 1
73 * Define this to turn on memory pool names.
75 #ifndef ISC_MEMPOOL_NAMES
76 #define ISC_MEMPOOL_NAMES 1
81 * log (to isc_lctx) each allocation and free.
84 * remember each allocation, and match them up on free. Crash if
85 * a free doesn't match an allocation
87 * if a hi_water mark is set print the maximium inuse memory every
88 * time it is raised once it exceeds the hi_water mark
90 LIBISC_EXTERNAL_DATA
extern unsigned int isc_mem_debugging
;
91 #define ISC_MEM_DEBUGTRACE 0x00000001U
92 #define ISC_MEM_DEBUGRECORD 0x00000002U
93 #define ISC_MEM_DEBUGUSAGE 0x00000004U
95 #if ISC_MEM_TRACKLINES
96 #define _ISC_MEM_FILELINE , __FILE__, __LINE__
97 #define _ISC_MEM_FLARG , const char *, int
99 #define _ISC_MEM_FILELINE
100 #define _ISC_MEM_FLARG
103 #define isc_mem_get(c, s) isc__mem_get((c), (s) _ISC_MEM_FILELINE)
104 #define isc_mem_allocate(c, s) isc__mem_allocate((c), (s) _ISC_MEM_FILELINE)
105 #define isc_mem_strdup(c, p) isc__mem_strdup((c), (p) _ISC_MEM_FILELINE)
106 #define isc_mempool_get(c) isc__mempool_get((c) _ISC_MEM_FILELINE)
109 * isc_mem_putanddetach() is a convienence function for use where you
110 * have a structure with an attached memory context.
122 * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
124 * is the equivalent of:
127 * isc_mem_attach(ptr->mctx, &mctx);
128 * isc_mem_detach(&ptr->mctx);
129 * isc_mem_put(mctx, ptr, sizeof(*ptr));
130 * isc_mem_detach(&mctx);
134 #define isc_mem_put(c, p, s) \
136 isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE); \
139 #define isc_mem_putanddetach(c, p, s) \
141 isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE); \
144 #define isc_mem_free(c, p) \
146 isc__mem_free((c), (p) _ISC_MEM_FILELINE); \
149 #define isc_mempool_put(c, p) \
151 isc__mempool_put((c), (p) _ISC_MEM_FILELINE); \
155 #define isc_mem_put(c, p, s) isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE)
156 #define isc_mem_putanddetach(c, p, s) \
157 isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE)
158 #define isc_mem_free(c, p) isc__mem_free((c), (p) _ISC_MEM_FILELINE)
159 #define isc_mempool_put(c, p) isc__mempool_put((c), (p) _ISC_MEM_FILELINE)
163 isc_mem_create(size_t max_size
, size_t target_size
,
167 isc_mem_createx(size_t max_size
, size_t target_size
,
168 isc_memalloc_t memalloc
, isc_memfree_t memfree
,
169 void *arg
, isc_mem_t
**mctxp
);
171 * Create a memory context.
173 * 'max_size' and 'target_size' are tuning parameters. When
174 * ISC_MEM_USE_INTERNAL_MALLOC is true, allocations smaller than
175 * 'max_size' will be satisfied by getting blocks of size
176 * 'target_size' from the system allocator and breaking them up into
177 * pieces; larger allocations will use the system allocator directly.
178 * If 'max_size' and/or 'target_size' are zero, default values will be
179 * used. When ISC_MEM_USE_INTERNAL_MALLOC is false, 'max_size' and
180 * 'target_size' are ignored.
182 * A memory context created using isc_mem_createx() will obtain
183 * memory from the system by calling 'memalloc' and 'memfree',
184 * passing them the argument 'arg'. A memory context created
185 * using isc_mem_create() will use the standard library malloc()
189 * mctxp != NULL && *mctxp == NULL */
192 isc_mem_attach(isc_mem_t
*, isc_mem_t
**);
194 isc_mem_detach(isc_mem_t
**);
196 * Attach to / detach from a memory context.
198 * This is intended for applications that use multiple memory contexts
199 * in such a way that it is not obvious when the last allocations from
200 * a given context has been freed and destroying the context is safe.
202 * Most applications do not need to call these functions as they can
203 * simply create a single memory context at the beginning of main()
204 * and destroy it at the end of main(), thereby guaranteeing that it
205 * is not destroyed while there are outstanding allocations.
209 isc_mem_destroy(isc_mem_t
**);
211 * Destroy a memory context.
215 isc_mem_ondestroy(isc_mem_t
*ctx
,
217 isc_event_t
**event
);
219 * Request to be notified with an event when a memory context has
220 * been successfully destroyed.
224 isc_mem_stats(isc_mem_t
*mctx
, FILE *out
);
226 * Print memory usage statistics for 'mctx' on the stream 'out'.
230 isc_mem_setdestroycheck(isc_mem_t
*mctx
,
233 * Iff 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
234 * destroyed and abort the program if any are present.
238 isc_mem_setquota(isc_mem_t
*, size_t);
240 isc_mem_getquota(isc_mem_t
*);
242 * Set/get the memory quota of 'mctx'. This is a hard limit
243 * on the amount of memory that may be allocated from mctx;
244 * if it is exceeded, allocations will fail.
248 isc_mem_inuse(isc_mem_t
*mctx
);
250 * Get an estimate of the number of memory in use in 'mctx', in bytes.
251 * This includes quantization overhead, but does not include memory
252 * allocated from the system but not yet used.
256 isc_mem_setwater(isc_mem_t
*mctx
, isc_mem_water_t water
, void *water_arg
,
257 size_t hiwater
, size_t lowater
);
259 * Set high and low water marks for this memory context. When the memory
260 * usage of 'mctx' exceeds 'hiwater', '(water)(water_arg, ISC_MEM_HIWATER)'
261 * will be called. When the usage drops below 'lowater', 'water' will
262 * again be called, this time with ISC_MEM_LOWATER.
264 * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
265 * ignored and the state is reset.
269 * 'water' is not NULL.
270 * hi_water >= lo_water
278 isc_mempool_create(isc_mem_t
*mctx
, size_t size
, isc_mempool_t
**mpctxp
);
280 * Create a memory pool.
283 * mctx is a valid memory context.
285 * mpctxp != NULL and *mpctxp == NULL
288 * maxalloc = UINT_MAX
293 * ISC_R_NOMEMORY -- not enough memory to create pool
294 * ISC_R_SUCCESS -- all is well.
298 isc_mempool_destroy(isc_mempool_t
**mpctxp
);
300 * Destroy a memory pool.
303 * mpctxp != NULL && *mpctxp is a valid pool.
304 * The pool has no un"put" allocations outstanding
308 isc_mempool_setname(isc_mempool_t
*mpctx
, const char *name
);
310 * Associate a name with a memory pool. At most 15 characters may be used.
313 * mpctx is a valid pool.
318 isc_mempool_associatelock(isc_mempool_t
*mpctx
, isc_mutex_t
*lock
);
320 * Associate a lock with this memory pool.
322 * This lock is used when getting or putting items using this memory pool,
323 * and it is also used to set or get internal state via the isc_mempool_get*()
324 * and isc_mempool_set*() set of functions.
326 * Mutiple pools can each share a single lock. For instance, if "manager"
327 * type object contained pools for various sizes of events, and each of
328 * these pools used a common lock. Note that this lock must NEVER be used
329 * by other than mempool routines once it is given to a pool, since that can
330 * easily cause double locking.
334 * mpctpx is a valid pool.
338 * No previous lock is assigned to this pool.
340 * The lock is initialized before calling this function via the normal
341 * means of doing that.
345 * The following functions get/set various parameters. Note that due to
346 * the unlocked nature of pools these are potentially random values unless
347 * the imposed externally provided locking protocols are followed.
349 * Also note that the quota limits will not always take immediate effect.
350 * For instance, setting "maxalloc" to a number smaller than the currently
351 * allocated count is permitted. New allocations will be refused until
352 * the count drops below this threshold.
354 * All functions require (in addition to other requirements):
355 * mpctx is a valid memory pool
359 isc_mempool_getfreemax(isc_mempool_t
*mpctx
);
361 * Returns the maximum allowed size of the free list.
365 isc_mempool_setfreemax(isc_mempool_t
*mpctx
, unsigned int limit
);
367 * Sets the maximum allowed size of the free list.
371 isc_mempool_getfreecount(isc_mempool_t
*mpctx
);
373 * Returns current size of the free list.
377 isc_mempool_getmaxalloc(isc_mempool_t
*mpctx
);
379 * Returns the maximum allowed number of allocations.
383 isc_mempool_setmaxalloc(isc_mempool_t
*mpctx
, unsigned int limit
);
385 * Sets the maximum allowed number of allocations.
387 * Additional requirements:
392 isc_mempool_getallocated(isc_mempool_t
*mpctx
);
394 * Returns the number of items allocated from this pool.
398 isc_mempool_getfillcount(isc_mempool_t
*mpctx
);
400 * Returns the number of items allocated as a block from the parent memory
401 * context when the free list is empty.
405 isc_mempool_setfillcount(isc_mempool_t
*mpctx
, unsigned int limit
);
407 * Sets the fillcount.
409 * Additional requirements:
415 * Pseudo-private functions for use via macros. Do not call directly.
418 isc__mem_get(isc_mem_t
*, size_t _ISC_MEM_FLARG
);
420 isc__mem_putanddetach(isc_mem_t
**, void *,
421 size_t _ISC_MEM_FLARG
);
423 isc__mem_put(isc_mem_t
*, void *, size_t _ISC_MEM_FLARG
);
425 isc__mem_allocate(isc_mem_t
*, size_t _ISC_MEM_FLARG
);
427 isc__mem_free(isc_mem_t
*, void * _ISC_MEM_FLARG
);
429 isc__mem_strdup(isc_mem_t
*, const char *_ISC_MEM_FLARG
);
431 isc__mempool_get(isc_mempool_t
* _ISC_MEM_FLARG
);
433 isc__mempool_put(isc_mempool_t
*, void * _ISC_MEM_FLARG
);
437 #endif /* ISC_MEM_H */