BIND: update vendor tree to 9.5.2-P2
[dragonfly.git] / contrib / bind / lib / isc / include / isc / mem.h
CommitLineData
bbbf71a3
JL
1/*
2 * Copyright (C) 2004-2009 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/* $Id: mem.h,v 1.72.128.6 2009/02/11 03:09:55 jinmei Exp $ */
19
20#ifndef ISC_MEM_H
21#define ISC_MEM_H 1
22
23/*! \file isc/mem.h */
24
25#include <stdio.h>
26
27#include <isc/lang.h>
28#include <isc/mutex.h>
29#include <isc/platform.h>
30#include <isc/types.h>
31#include <isc/xml.h>
32
33ISC_LANG_BEGINDECLS
34
35#define ISC_MEM_LOWATER 0
36#define ISC_MEM_HIWATER 1
37typedef void (*isc_mem_water_t)(void *, int);
38
39typedef void * (*isc_memalloc_t)(void *, size_t);
40typedef void (*isc_memfree_t)(void *, void *);
41
42/*%
43 * Define ISC_MEM_DEBUG=1 to make all functions that free memory
44 * set the pointer being freed to NULL after being freed.
45 * This is the default; set ISC_MEM_DEBUG=0 to disable it.
46 */
47#ifndef ISC_MEM_DEBUG
48#define ISC_MEM_DEBUG 1
49#endif
50
51/*%
52 * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory
53 * allocation and freeing by file and line number.
54 */
55#ifndef ISC_MEM_TRACKLINES
56#define ISC_MEM_TRACKLINES 1
57#endif
58
59/*%
60 * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
61 * the requested space. This will increase the size of each allocation.
62 */
63#ifndef ISC_MEM_CHECKOVERRUN
64#define ISC_MEM_CHECKOVERRUN 1
65#endif
66
67/*%
68 * Define ISC_MEM_FILL=1 to fill each block of memory returned to the system
69 * with the byte string '0xbe'. This helps track down uninitialized pointers
70 * and the like. On freeing memory, the space is filled with '0xde' for
71 * the same reasons.
72 */
73#ifndef ISC_MEM_FILL
74#define ISC_MEM_FILL 1
75#endif
76
77/*%
78 * Define ISC_MEMPOOL_NAMES=1 to make memory pools store a symbolic
79 * name so that the leaking pool can be more readily identified in
80 * case of a memory leak.
81 */
82#ifndef ISC_MEMPOOL_NAMES
83#define ISC_MEMPOOL_NAMES 1
84#endif
85
86LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging;
87/*@{*/
88#define ISC_MEM_DEBUGTRACE 0x00000001U
89#define ISC_MEM_DEBUGRECORD 0x00000002U
90#define ISC_MEM_DEBUGUSAGE 0x00000004U
91#define ISC_MEM_DEBUGSIZE 0x00000008U
92#define ISC_MEM_DEBUGCTX 0x00000010U
93#define ISC_MEM_DEBUGALL 0x0000001FU
94/*!<
95 * The variable isc_mem_debugging holds a set of flags for
96 * turning certain memory debugging options on or off at
97 * runtime. It is initialized to the value ISC_MEM_DEGBUGGING,
98 * which is 0 by default but may be overridden at compile time.
99 * The following flags can be specified:
100 *
101 * \li #ISC_MEM_DEBUGTRACE
102 * Log each allocation and free to isc_lctx.
103 *
104 * \li #ISC_MEM_DEBUGRECORD
105 * Remember each allocation, and match them up on free.
106 * Crash if a free doesn't match an allocation.
107 *
108 * \li #ISC_MEM_DEBUGUSAGE
109 * If a hi_water mark is set, print the maximum inuse memory
110 * every time it is raised once it exceeds the hi_water mark.
111 *
112 * \li #ISC_MEM_DEBUGSIZE
113 * Check the size argument being passed to isc_mem_put() matches
114 * that passed to isc_mem_get().
115 *
116 * \li #ISC_MEM_DEBUGCTX
117 * Check the mctx argument being passed to isc_mem_put() matches
118 * that passed to isc_mem_get().
119 */
120/*@}*/
121
122#if ISC_MEM_TRACKLINES
123#define _ISC_MEM_FILELINE , __FILE__, __LINE__
124#define _ISC_MEM_FLARG , const char *, int
125#else
126#define _ISC_MEM_FILELINE
127#define _ISC_MEM_FLARG
128#endif
129
130/*!
131 * Define ISC_MEM_USE_INTERNAL_MALLOC=1 to use the internal malloc()
132 * implementation in preference to the system one. The internal malloc()
133 * is very space-efficient, and quite fast on uniprocessor systems. It
134 * performs poorly on multiprocessor machines.
135 * JT: we can overcome the performance issue on multiprocessor machines
136 * by carefully separating memory contexts.
137 */
138
139#ifndef ISC_MEM_USE_INTERNAL_MALLOC
140#define ISC_MEM_USE_INTERNAL_MALLOC 1
141#endif
142
143/*
144 * Flags for isc_mem_create2()calls.
145 */
146#define ISC_MEMFLAG_NOLOCK 0x00000001 /* no lock is necessary */
147#define ISC_MEMFLAG_INTERNAL 0x00000002 /* use internal malloc */
148#if ISC_MEM_USE_INTERNAL_MALLOC
149#define ISC_MEMFLAG_DEFAULT ISC_MEMFLAG_INTERNAL
150#else
151#define ISC_MEMFLAG_DEFAULT 0
152#endif
153
154
155#define isc_mem_get(c, s) isc__mem_get((c), (s) _ISC_MEM_FILELINE)
156#define isc_mem_allocate(c, s) isc__mem_allocate((c), (s) _ISC_MEM_FILELINE)
157#define isc_mem_reallocate(c, p, s) isc__mem_reallocate((c), (p), (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)
160
161/*%
162 * isc_mem_putanddetach() is a convenience function for use where you
163 * have a structure with an attached memory context.
164 *
165 * Given:
166 *
167 * \code
168 * struct {
169 * ...
170 * isc_mem_t *mctx;
171 * ...
172 * } *ptr;
173 *
174 * isc_mem_t *mctx;
175 *
176 * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
177 * \endcode
178 *
179 * is the equivalent of:
180 *
181 * \code
182 * mctx = NULL;
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);
187 * \endcode
188 */
189
190#if ISC_MEM_DEBUG
191#define isc_mem_put(c, p, s) \
192 do { \
193 isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE); \
194 (p) = NULL; \
195 } while (0)
196#define isc_mem_putanddetach(c, p, s) \
197 do { \
198 isc__mem_putanddetach((c), (p), (s) _ISC_MEM_FILELINE); \
199 (p) = NULL; \
200 } while (0)
201#define isc_mem_free(c, p) \
202 do { \
203 isc__mem_free((c), (p) _ISC_MEM_FILELINE); \
204 (p) = NULL; \
205 } while (0)
206#define isc_mempool_put(c, p) \
207 do { \
208 isc__mempool_put((c), (p) _ISC_MEM_FILELINE); \
209 (p) = NULL; \
210 } while (0)
211#else
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)
217#endif
218
219/*@{*/
220isc_result_t
221isc_mem_create(size_t max_size, size_t target_size,
222 isc_mem_t **mctxp);
223
224isc_result_t
225isc_mem_create2(size_t max_size, size_t target_size,
226 isc_mem_t **mctxp, unsigned int flags);
227
228isc_result_t
229isc_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);
232
233isc_result_t
234isc_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);
237
238/*!<
239 * \brief Create a memory context.
240 *
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.
248 *
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.
252 *
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()
257 * and free().
258 *
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.
264 *
265 * Requires:
266 * mctxp != NULL && *mctxp == NULL */
267/*@}*/
268
269/*@{*/
270void
271isc_mem_attach(isc_mem_t *, isc_mem_t **);
272void
273isc_mem_detach(isc_mem_t **);
274/*!<
275 * \brief Attach to / detach from a memory context.
276 *
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.
280 *
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.
285 */
286/*@}*/
287
288void
289isc_mem_destroy(isc_mem_t **);
290/*%<
291 * Destroy a memory context.
292 */
293
294isc_result_t
295isc_mem_ondestroy(isc_mem_t *ctx,
296 isc_task_t *task,
297 isc_event_t **event);
298/*%<
299 * Request to be notified with an event when a memory context has
300 * been successfully destroyed.
301 */
302
303void
304isc_mem_stats(isc_mem_t *mctx, FILE *out);
305/*%<
306 * Print memory usage statistics for 'mctx' on the stream 'out'.
307 */
308
309void
310isc_mem_setdestroycheck(isc_mem_t *mctx,
311 isc_boolean_t on);
312/*%<
313 * If 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
314 * destroyed and abort the program if any are present.
315 */
316
317/*@{*/
318void
319isc_mem_setquota(isc_mem_t *, size_t);
320size_t
321isc_mem_getquota(isc_mem_t *);
322/*%<
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.
326 */
327/*@}*/
328
329size_t
330isc_mem_inuse(isc_mem_t *mctx);
331/*%<
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.
335 */
336
337void
338isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
339 size_t hiwater, size_t lowater);
340/*%<
341 * Set high and low water marks for this memory context.
342 *
343 * When the memory usage of 'mctx' exceeds 'hiwater',
344 * '(water)(water_arg, #ISC_MEM_HIWATER)' will be called. 'water' needs to
345 * call isc_mem_waterack() with #ISC_MEM_HIWATER to acknowledge the state
346 * change. 'water' may be called multiple times.
347 *
348 * When the usage drops below 'lowater', 'water' will again be called, this
349 * time with #ISC_MEM_LOWATER. 'water' need to calls isc_mem_waterack() with
350 * #ISC_MEM_LOWATER to acknowledge the change.
351 *
352 * static void
353 * water(void *arg, int mark) {
354 * struct foo *foo = arg;
355 *
356 * LOCK(&foo->marklock);
357 * if (foo->mark != mark) {
358 * foo->mark = mark;
359 * ....
360 * isc_mem_waterack(foo->mctx, mark);
361 * }
362 * UNLOCK(&foo->marklock);
363 * }
364 * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
365 * ignored and the state is reset.
366 *
367 * Requires:
368 *
369 * 'water' is not NULL.
370 * hi_water >= lo_water
371 */
372
373void
374isc_mem_waterack(isc_mem_t *ctx, int mark);
375/*%<
376 * Called to acknowledge changes in signaled by calls to 'water'.
377 */
378
379void
380isc_mem_printactive(isc_mem_t *mctx, FILE *file);
381/*%<
382 * Print to 'file' all active memory in 'mctx'.
383 *
384 * Requires ISC_MEM_DEBUGRECORD to have been set.
385 */
386
387void
388isc_mem_printallactive(FILE *file);
389/*%<
390 * Print to 'file' all active memory in all contexts.
391 *
392 * Requires ISC_MEM_DEBUGRECORD to have been set.
393 */
394
395void
396isc_mem_checkdestroyed(FILE *file);
397/*%<
398 * Check that all memory contexts have been destroyed.
399 * Prints out those that have not been.
400 * Fatally fails if there are still active contexts.
401 */
402
403void
404isc_mem_setname(isc_mem_t *ctx, const char *name, void *tag);
405/*%<
406 * Name 'ctx'.
407 *
408 * Notes:
409 *
410 *\li Only the first 15 characters of 'name' will be copied.
411 *
412 *\li 'tag' is for debugging purposes only.
413 *
414 * Requires:
415 *
416 *\li 'ctx' is a valid ctx.
417 */
418
419const char *
420isc_mem_getname(isc_mem_t *ctx);
421/*%<
422 * Get the name of 'ctx', as previously set using isc_mem_setname().
423 *
424 * Requires:
425 *\li 'ctx' is a valid ctx.
426 *
427 * Returns:
428 *\li A non-NULL pointer to a null-terminated string.
429 * If the ctx has not been named, the string is
430 * empty.
431 */
432
433void *
434isc_mem_gettag(isc_mem_t *ctx);
435/*%<
436 * Get the tag value for 'task', as previously set using isc_mem_setname().
437 *
438 * Requires:
439 *\li 'ctx' is a valid ctx.
440 *
441 * Notes:
442 *\li This function is for debugging purposes only.
443 *
444 * Requires:
445 *\li 'ctx' is a valid task.
446 */
447
448#ifdef HAVE_LIBXML2
449void
450isc_mem_renderxml(xmlTextWriterPtr writer);
451/*%<
452 * Render all contexts' statistics and status in XML for writer.
453 */
454#endif /* HAVE_LIBXML2 */
455
456/*
457 * Memory pools
458 */
459
460isc_result_t
461isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
462/*%<
463 * Create a memory pool.
464 *
465 * Requires:
466 *\li mctx is a valid memory context.
467 *\li size > 0
468 *\li mpctxp != NULL and *mpctxp == NULL
469 *
470 * Defaults:
471 *\li maxalloc = UINT_MAX
472 *\li freemax = 1
473 *\li fillcount = 1
474 *
475 * Returns:
476 *\li #ISC_R_NOMEMORY -- not enough memory to create pool
477 *\li #ISC_R_SUCCESS -- all is well.
478 */
479
480void
481isc_mempool_destroy(isc_mempool_t **mpctxp);
482/*%<
483 * Destroy a memory pool.
484 *
485 * Requires:
486 *\li mpctxp != NULL && *mpctxp is a valid pool.
487 *\li The pool has no un"put" allocations outstanding
488 */
489
490void
491isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
492/*%<
493 * Associate a name with a memory pool. At most 15 characters may be used.
494 *
495 * Requires:
496 *\li mpctx is a valid pool.
497 *\li name != NULL;
498 */
499
500void
501isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
502/*%<
503 * Associate a lock with this memory pool.
504 *
505 * This lock is used when getting or putting items using this memory pool,
506 * and it is also used to set or get internal state via the isc_mempool_get*()
507 * and isc_mempool_set*() set of functions.
508 *
509 * Multiple pools can each share a single lock. For instance, if "manager"
510 * type object contained pools for various sizes of events, and each of
511 * these pools used a common lock. Note that this lock must NEVER be used
512 * by other than mempool routines once it is given to a pool, since that can
513 * easily cause double locking.
514 *
515 * Requires:
516 *
517 *\li mpctpx is a valid pool.
518 *
519 *\li lock != NULL.
520 *
521 *\li No previous lock is assigned to this pool.
522 *
523 *\li The lock is initialized before calling this function via the normal
524 * means of doing that.
525 */
526
527/*
528 * The following functions get/set various parameters. Note that due to
529 * the unlocked nature of pools these are potentially random values unless
530 * the imposed externally provided locking protocols are followed.
531 *
532 * Also note that the quota limits will not always take immediate effect.
533 * For instance, setting "maxalloc" to a number smaller than the currently
534 * allocated count is permitted. New allocations will be refused until
535 * the count drops below this threshold.
536 *
537 * All functions require (in addition to other requirements):
538 * mpctx is a valid memory pool
539 */
540
541unsigned int
542isc_mempool_getfreemax(isc_mempool_t *mpctx);
543/*%<
544 * Returns the maximum allowed size of the free list.
545 */
546
547void
548isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
549/*%<
550 * Sets the maximum allowed size of the free list.
551 */
552
553unsigned int
554isc_mempool_getfreecount(isc_mempool_t *mpctx);
555/*%<
556 * Returns current size of the free list.
557 */
558
559unsigned int
560isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
561/*!<
562 * Returns the maximum allowed number of allocations.
563 */
564
565void
566isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
567/*%<
568 * Sets the maximum allowed number of allocations.
569 *
570 * Additional requirements:
571 *\li limit > 0
572 */
573
574unsigned int
575isc_mempool_getallocated(isc_mempool_t *mpctx);
576/*%<
577 * Returns the number of items allocated from this pool.
578 */
579
580unsigned int
581isc_mempool_getfillcount(isc_mempool_t *mpctx);
582/*%<
583 * Returns the number of items allocated as a block from the parent memory
584 * context when the free list is empty.
585 */
586
587void
588isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
589/*%<
590 * Sets the fillcount.
591 *
592 * Additional requirements:
593 *\li limit > 0
594 */
595
596
597/*
598 * Pseudo-private functions for use via macros. Do not call directly.
599 */
600void *
601isc__mem_get(isc_mem_t *, size_t _ISC_MEM_FLARG);
602void
603isc__mem_putanddetach(isc_mem_t **, void *,
604 size_t _ISC_MEM_FLARG);
605void
606isc__mem_put(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
607void *
608isc__mem_allocate(isc_mem_t *, size_t _ISC_MEM_FLARG);
609void *
610isc__mem_reallocate(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
611void
612isc__mem_free(isc_mem_t *, void * _ISC_MEM_FLARG);
613char *
614isc__mem_strdup(isc_mem_t *, const char *_ISC_MEM_FLARG);
615void *
616isc__mempool_get(isc_mempool_t * _ISC_MEM_FLARG);
617void
618isc__mempool_put(isc_mempool_t *, void * _ISC_MEM_FLARG);
619
620ISC_LANG_ENDDECLS
621
622#endif /* ISC_MEM_H */