2
* Copyright (C) 2004-2007 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.2 2007/11/16 11:04:11 shane Exp $ */
23
/*! \file isc/mem.h */
27
#include <isc-dhcp/lang.h>
28
/*#include <isc-dhcp/mutex.h>*/
29
/*#include <isc-dhcp/platform.h>*/
30
#include <isc-dhcp/types.h>
31
/*#include <isc-dhcp/xml.h>*/
32
#include <isc-dhcp/result.h>
36
#define ISC_MEM_LOWATER 0
37
#define ISC_MEM_HIWATER 1
38
typedef void (*isc_mem_water_t)(void *, int);
40
typedef void * (*isc_memalloc_t)(void *, size_t);
41
typedef void (*isc_memfree_t)(void *, void *);
44
* Define ISC_MEM_DEBUG=1 to make all functions that free memory
45
* set the pointer being freed to NULL after being freed.
46
* This is the default; set ISC_MEM_DEBUG=0 to disable it.
49
#define ISC_MEM_DEBUG 1
53
* Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory
54
* allocation and freeing by file and line number.
56
#ifndef ISC_MEM_TRACKLINES
57
#define ISC_MEM_TRACKLINES 1
61
* Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
62
* the requested space. This will increase the size of each allocation.
64
#ifndef ISC_MEM_CHECKOVERRUN
65
#define ISC_MEM_CHECKOVERRUN 1
69
* Define ISC_MEM_FILL=1 to fill each block of memory returned to the system
70
* with the byte string '0xbe'. This helps track down uninitialized pointers
71
* and the like. On freeing memory, the space is filled with '0xde' for
75
#define ISC_MEM_FILL 1
79
* Define ISC_MEMPOOL_NAMES=1 to make memory pools store a symbolic
80
* name so that the leaking pool can be more readily identified in
81
* case of a memory leak.
83
#ifndef ISC_MEMPOOL_NAMES
84
#define ISC_MEMPOOL_NAMES 1
87
extern unsigned int isc_mem_debugging;
89
#define ISC_MEM_DEBUGTRACE 0x00000001U
90
#define ISC_MEM_DEBUGRECORD 0x00000002U
91
#define ISC_MEM_DEBUGUSAGE 0x00000004U
92
#define ISC_MEM_DEBUGSIZE 0x00000008U
93
#define ISC_MEM_DEBUGCTX 0x00000010U
94
#define ISC_MEM_DEBUGALL 0x0000001FU
96
* The variable isc_mem_debugging holds a set of flags for
97
* turning certain memory debugging options on or off at
98
* runtime. Its is intialized to the value ISC_MEM_DEGBUGGING,
99
* which is 0 by default but may be overridden at compile time.
100
* The following flags can be specified:
102
* \li #ISC_MEM_DEBUGTRACE
103
* Log each allocation and free to isc_lctx.
105
* \li #ISC_MEM_DEBUGRECORD
106
* Remember each allocation, and match them up on free.
107
* Crash if a free doesn't match an allocation.
109
* \li #ISC_MEM_DEBUGUSAGE
110
* If a hi_water mark is set, print the maximium inuse memory
111
* every time it is raised once it exceeds the hi_water mark.
113
* \li #ISC_MEM_DEBUGSIZE
114
* Check the size argument being passed to isc_mem_put() matches
115
* that passed to isc_mem_get().
117
* \li #ISC_MEM_DEBUGCTX
118
* Check the mctx argument being passed to isc_mem_put() matches
119
* that passed to isc_mem_get().
123
#if ISC_MEM_TRACKLINES
124
#define _ISC_MEM_FILELINE , __FILE__, __LINE__
125
#define _ISC_MEM_FLARG , const char *, int
127
#define _ISC_MEM_FILELINE
128
#define _ISC_MEM_FLARG
132
* Define ISC_MEM_USE_INTERNAL_MALLOC=1 to use the internal malloc()
133
* implementation in preference to the system one. The internal malloc()
134
* is very space-efficient, and quite fast on uniprocessor systems. It
135
* performs poorly on multiprocessor machines.
136
* JT: we can overcome the performance issue on multiprocessor machines
137
* by carefully separating memory contexts.
140
#ifndef ISC_MEM_USE_INTERNAL_MALLOC
141
#define ISC_MEM_USE_INTERNAL_MALLOC 1
145
* Flags for isc_mem_create2()calls.
147
#define ISC_MEMFLAG_NOLOCK 0x00000001 /* no lock is necessary */
148
#define ISC_MEMFLAG_INTERNAL 0x00000002 /* use internal malloc */
149
#if ISC_MEM_USE_INTERNAL_MALLOC
150
#define ISC_MEMFLAG_DEFAULT ISC_MEMFLAG_INTERNAL
152
#define ISC_MEMFLAG_DEFAULT 0
156
#define isc_mem_get(c, s) isc__mem_get((c), (s) _ISC_MEM_FILELINE)
157
#define isc_mem_allocate(c, s) isc__mem_allocate((c), (s) _ISC_MEM_FILELINE)
158
#define isc_mem_strdup(c, p) isc__mem_strdup((c), (p) _ISC_MEM_FILELINE)
159
#define isc_mempool_get(c) isc__mempool_get((c) _ISC_MEM_FILELINE)
162
* isc_mem_putanddetach() is a convienence function for use where you
163
* have a structure with an attached memory context.
176
* isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
179
* is the equivalent of:
183
* isc_mem_attach(ptr->mctx, &mctx);
184
* isc_mem_detach(&ptr->mctx);
185
* isc_mem_put(mctx, ptr, sizeof(*ptr));
186
* isc_mem_detach(&mctx);
191
#define isc_mem_put(c, p, s) \
193
isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE); \
196
#define isc_mem_putanddetach(c, p, s) \
198
isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE); \
201
#define isc_mem_free(c, p) \
203
isc__mem_free((c), (p) _ISC_MEM_FILELINE); \
206
#define isc_mempool_put(c, p) \
208
isc__mempool_put((c), (p) _ISC_MEM_FILELINE); \
212
#define isc_mem_put(c, p, s) isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE)
213
#define isc_mem_putanddetach(c, p, s) \
214
isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE)
215
#define isc_mem_free(c, p) isc__mem_free((c), (p) _ISC_MEM_FILELINE)
216
#define isc_mempool_put(c, p) isc__mempool_put((c), (p) _ISC_MEM_FILELINE)
221
isc_mem_create(size_t max_size, size_t target_size,
225
isc_mem_create2(size_t max_size, size_t target_size,
226
isc_mem_t **mctxp, unsigned int flags);
229
isc_mem_createx(size_t max_size, size_t target_size,
230
isc_memalloc_t memalloc, isc_memfree_t memfree,
231
void *arg, isc_mem_t **mctxp);
234
isc_mem_createx2(size_t max_size, size_t target_size,
235
isc_memalloc_t memalloc, isc_memfree_t memfree,
236
void *arg, isc_mem_t **mctxp, unsigned int flags);
239
* \brief Create a memory context.
241
* 'max_size' and 'target_size' are tuning parameters. When
242
* ISC_MEMFLAG_INTERNAL is set, allocations smaller than 'max_size'
243
* will be satisfied by getting blocks of size 'target_size' from the
244
* system allocator and breaking them up into pieces; larger allocations
245
* will use the system allocator directly. If 'max_size' and/or
246
* 'target_size' are zero, default values will be * used. When
247
* ISC_MEMFLAG_INTERNAL is not set, 'target_size' is ignored.
249
* 'max_size' is also used to size the statistics arrays and the array
250
* used to record active memory when ISC_MEM_DEBUGRECORD is set. Settin
251
* 'max_size' too low can have detrimental effects on performance.
253
* A memory context created using isc_mem_createx() will obtain
254
* memory from the system by calling 'memalloc' and 'memfree',
255
* passing them the argument 'arg'. A memory context created
256
* using isc_mem_create() will use the standard library malloc()
259
* If ISC_MEMFLAG_NOLOCK is set in 'flags', the corresponding memory context
260
* will be accessed without locking. The user who creates the context must
261
* ensure there be no race. Since this can be a source of bug, it is generally
262
* inadvisable to use this flag unless the user is very sure about the race
263
* condition and the access to the object is highly performance sensitive.
266
* mctxp != NULL && *mctxp == NULL */
271
isc_mem_attach(isc_mem_t *, isc_mem_t **);
273
isc_mem_detach(isc_mem_t **);
275
* \brief Attach to / detach from a memory context.
277
* This is intended for applications that use multiple memory contexts
278
* in such a way that it is not obvious when the last allocations from
279
* a given context has been freed and destroying the context is safe.
281
* Most applications do not need to call these functions as they can
282
* simply create a single memory context at the beginning of main()
283
* and destroy it at the end of main(), thereby guaranteeing that it
284
* is not destroyed while there are outstanding allocations.
289
isc_mem_destroy(isc_mem_t **);
291
* Destroy a memory context.
295
isc_mem_ondestroy(isc_mem_t *ctx,
297
isc_event_t **event);
299
* Request to be notified with an event when a memory context has
300
* been successfully destroyed.
304
isc_mem_stats(isc_mem_t *mctx, FILE *out);
306
* Print memory usage statistics for 'mctx' on the stream 'out'.
310
isc_mem_setdestroycheck(isc_mem_t *mctx,
313
* If 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
314
* destroyed and abort the program if any are present.
319
isc_mem_setquota(isc_mem_t *, size_t);
321
isc_mem_getquota(isc_mem_t *);
323
* Set/get the memory quota of 'mctx'. This is a hard limit
324
* on the amount of memory that may be allocated from mctx;
325
* if it is exceeded, allocations will fail.
330
isc_mem_inuse(isc_mem_t *mctx);
332
* Get an estimate of the number of memory in use in 'mctx', in bytes.
333
* This includes quantization overhead, but does not include memory
334
* allocated from the system but not yet used.
338
isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
339
size_t hiwater, size_t lowater);
341
* Set high and low water marks for this memory context.
344
* usage of 'mctx' exceeds 'hiwater', '(water)(water_arg, #ISC_MEM_HIWATER)'
345
* will be called. When the usage drops below 'lowater', 'water' will
346
* again be called, this time with #ISC_MEM_LOWATER.
348
* If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
349
* ignored and the state is reset.
353
* 'water' is not NULL.
354
* hi_water >= lo_water
358
isc_mem_printactive(isc_mem_t *mctx, FILE *file);
360
* Print to 'file' all active memory in 'mctx'.
362
* Requires ISC_MEM_DEBUGRECORD to have been set.
366
isc_mem_printallactive(FILE *file);
368
* Print to 'file' all active memory in all contexts.
370
* Requires ISC_MEM_DEBUGRECORD to have been set.
374
isc_mem_checkdestroyed(FILE *file);
376
* Check that all memory contexts have been destroyed.
377
* Prints out those that have not been.
378
* Fatally fails if there are still active contexts.
386
isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
388
* Create a memory pool.
391
*\li mctx is a valid memory context.
393
*\li mpctxp != NULL and *mpctxp == NULL
396
*\li maxalloc = UINT_MAX
401
*\li #ISC_R_NOMEMORY -- not enough memory to create pool
402
*\li #ISC_R_SUCCESS -- all is well.
406
isc_mempool_destroy(isc_mempool_t **mpctxp);
408
* Destroy a memory pool.
411
*\li mpctxp != NULL && *mpctxp is a valid pool.
412
*\li The pool has no un"put" allocations outstanding
416
isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
418
* Associate a name with a memory pool. At most 15 characters may be used.
421
*\li mpctx is a valid pool.
427
isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
430
* Associate a lock with this memory pool.
432
* This lock is used when getting or putting items using this memory pool,
433
* and it is also used to set or get internal state via the isc_mempool_get*()
434
* and isc_mempool_set*() set of functions.
436
* Mutiple pools can each share a single lock. For instance, if "manager"
437
* type object contained pools for various sizes of events, and each of
438
* these pools used a common lock. Note that this lock must NEVER be used
439
* by other than mempool routines once it is given to a pool, since that can
440
* easily cause double locking.
444
*\li mpctpx is a valid pool.
448
*\li No previous lock is assigned to this pool.
450
*\li The lock is initialized before calling this function via the normal
451
* means of doing that.
455
* The following functions get/set various parameters. Note that due to
456
* the unlocked nature of pools these are potentially random values unless
457
* the imposed externally provided locking protocols are followed.
459
* Also note that the quota limits will not always take immediate effect.
460
* For instance, setting "maxalloc" to a number smaller than the currently
461
* allocated count is permitted. New allocations will be refused until
462
* the count drops below this threshold.
464
* All functions require (in addition to other requirements):
465
* mpctx is a valid memory pool
469
isc_mempool_getfreemax(isc_mempool_t *mpctx);
471
* Returns the maximum allowed size of the free list.
475
isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
477
* Sets the maximum allowed size of the free list.
481
isc_mempool_getfreecount(isc_mempool_t *mpctx);
483
* Returns current size of the free list.
487
isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
489
* Returns the maximum allowed number of allocations.
493
isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
495
* Sets the maximum allowed number of allocations.
497
* Additional requirements:
502
isc_mempool_getallocated(isc_mempool_t *mpctx);
504
* Returns the number of items allocated from this pool.
508
isc_mempool_getfillcount(isc_mempool_t *mpctx);
510
* Returns the number of items allocated as a block from the parent memory
511
* context when the free list is empty.
515
isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
517
* Sets the fillcount.
519
* Additional requirements:
525
* Pseudo-private functions for use via macros. Do not call directly.
528
isc__mem_get(isc_mem_t *, size_t _ISC_MEM_FLARG);
530
isc__mem_putanddetach(isc_mem_t **, void *,
531
size_t _ISC_MEM_FLARG);
533
isc__mem_put(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
535
isc__mem_allocate(isc_mem_t *, size_t _ISC_MEM_FLARG);
537
isc__mem_free(isc_mem_t *, void * _ISC_MEM_FLARG);
539
isc__mem_strdup(isc_mem_t *, const char *_ISC_MEM_FLARG);
541
isc__mempool_get(isc_mempool_t * _ISC_MEM_FLARG);
543
isc__mempool_put(isc_mempool_t *, void * _ISC_MEM_FLARG);
547
isc_mem_renderxml(isc_mem_t *mgr, xmlTextWriterPtr writer);
548
#endif /* HAVE_LIBXML2 */
552
#endif /* ISC_MEM_H */
added
removed
includes/isc-dhcp/mem.h
