mem.h 21.2 KB
Newer Older
Bob Halley's avatar
update  
Bob Halley committed
1
/*
Tinderbox User's avatar
Tinderbox User committed
2
 * Copyright (C) 2004-2013  Internet Systems Consortium, Inc. ("ISC")
Brian Wellington's avatar
Brian Wellington committed
3
 * Copyright (C) 1997-2001  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
Bob Halley's avatar
update  
Bob Halley committed
6 7
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
Bob Halley's avatar
update  
Bob Halley committed
16 17
 */

Mark Andrews's avatar
Mark Andrews committed
18
/* $Id$ */
David Lawrence's avatar
David Lawrence committed
19

20 21
#ifndef ISC_MEM_H
#define ISC_MEM_H 1
Bob Halley's avatar
update  
Bob Halley committed
22

23
/*! \file isc/mem.h */
24

Bob Halley's avatar
update  
Bob Halley committed
25 26
#include <stdio.h>

27
#include <isc/json.h>
Michael Graff's avatar
Michael Graff committed
28 29
#include <isc/lang.h>
#include <isc/mutex.h>
30
#include <isc/platform.h>
Michael Graff's avatar
Michael Graff committed
31
#include <isc/types.h>
32
#include <isc/xml.h>
Bob Halley's avatar
update  
Bob Halley committed
33

Bob Halley's avatar
Bob Halley committed
34 35
ISC_LANG_BEGINDECLS

36 37 38 39
#define ISC_MEM_LOWATER 0
#define ISC_MEM_HIWATER 1
typedef void (*isc_mem_water_t)(void *, int);

40 41 42
typedef void * (*isc_memalloc_t)(void *, size_t);
typedef void (*isc_memfree_t)(void *, void *);

43
/*%
44 45
 * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory
 * allocation and freeing by file and line number.
Michael Graff's avatar
Michael Graff committed
46
 */
47
#ifndef ISC_MEM_TRACKLINES
48
#define ISC_MEM_TRACKLINES 1
Michael Graff's avatar
Michael Graff committed
49 50
#endif

51
/*%
52
 * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside
Michael Graff's avatar
Michael Graff committed
53 54
 * the requested space.  This will increase the size of each allocation.
 */
55
#ifndef ISC_MEM_CHECKOVERRUN
56
#define ISC_MEM_CHECKOVERRUN 1
Michael Graff's avatar
Michael Graff committed
57 58
#endif

59
/*%
60
 * Define ISC_MEM_FILL=1 to fill each block of memory returned to the system
Michael Graff's avatar
Michael Graff committed
61 62 63 64
 * with the byte string '0xbe'.  This helps track down uninitialized pointers
 * and the like.  On freeing memory, the space is filled with '0xde' for
 * the same reasons.
 */
65 66 67
#ifndef ISC_MEM_FILL
#define ISC_MEM_FILL 1
#endif
Michael Graff's avatar
Michael Graff committed
68

69
/*%
70 71 72
 * Define ISC_MEMPOOL_NAMES=1 to make memory pools store a symbolic
 * name so that the leaking pool can be more readily identified in
 * case of a memory leak.
Michael Graff's avatar
Michael Graff committed
73
 */
74 75 76
#ifndef ISC_MEMPOOL_NAMES
#define ISC_MEMPOOL_NAMES 1
#endif
Michael Graff's avatar
Michael Graff committed
77

78
LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging;
79
/*@{*/
Michael Graff's avatar
Michael Graff committed
80 81
#define ISC_MEM_DEBUGTRACE		0x00000001U
#define ISC_MEM_DEBUGRECORD		0x00000002U
82
#define ISC_MEM_DEBUGUSAGE		0x00000004U
83 84 85
#define ISC_MEM_DEBUGSIZE		0x00000008U
#define ISC_MEM_DEBUGCTX		0x00000010U
#define ISC_MEM_DEBUGALL		0x0000001FU
86
/*!<
87 88
 * The variable isc_mem_debugging holds a set of flags for
 * turning certain memory debugging options on or off at
Francis Dupont's avatar
Francis Dupont committed
89
 * runtime.  It is initialized to the value ISC_MEM_DEGBUGGING,
90 91 92
 * which is 0 by default but may be overridden at compile time.
 * The following flags can be specified:
 *
93
 * \li #ISC_MEM_DEBUGTRACE
94 95
 *	Log each allocation and free to isc_lctx.
 *
96
 * \li #ISC_MEM_DEBUGRECORD
97 98 99
 *	Remember each allocation, and match them up on free.
 *	Crash if a free doesn't match an allocation.
 *
100
 * \li #ISC_MEM_DEBUGUSAGE
Francis Dupont's avatar
Francis Dupont committed
101
 *	If a hi_water mark is set, print the maximum inuse memory
102
 *	every time it is raised once it exceeds the hi_water mark.
103 104
 *
 * \li #ISC_MEM_DEBUGSIZE
Mark Andrews's avatar
Mark Andrews committed
105
 *	Check the size argument being passed to isc_mem_put() matches
106 107 108
 *	that passed to isc_mem_get().
 *
 * \li #ISC_MEM_DEBUGCTX
Mark Andrews's avatar
Mark Andrews committed
109
 *	Check the mctx argument being passed to isc_mem_put() matches
110
 *	that passed to isc_mem_get().
111
 */
112
/*@}*/
Michael Graff's avatar
Michael Graff committed
113

114
#if ISC_MEM_TRACKLINES
Michael Graff's avatar
Michael Graff committed
115
#define _ISC_MEM_FILELINE	, __FILE__, __LINE__
116
#define _ISC_MEM_FLARG		, const char *, unsigned int
Michael Graff's avatar
Michael Graff committed
117 118 119 120 121
#else
#define _ISC_MEM_FILELINE
#define _ISC_MEM_FLARG
#endif

122 123 124 125 126 127 128 129 130 131 132 133 134
/*!
 * Define ISC_MEM_USE_INTERNAL_MALLOC=1 to use the internal malloc()
 * implementation in preference to the system one.  The internal malloc()
 * is very space-efficient, and quite fast on uniprocessor systems.  It
 * performs poorly on multiprocessor machines.
 * JT: we can overcome the performance issue on multiprocessor machines
 * by carefully separating memory contexts.
 */

#ifndef ISC_MEM_USE_INTERNAL_MALLOC
#define ISC_MEM_USE_INTERNAL_MALLOC 1
#endif

135 136 137 138
/*
 * Flags for isc_mem_create2()calls.
 */
#define ISC_MEMFLAG_NOLOCK	0x00000001	 /* no lock is necessary */
139 140 141 142 143 144 145
#define ISC_MEMFLAG_INTERNAL	0x00000002	 /* use internal malloc */
#if ISC_MEM_USE_INTERNAL_MALLOC
#define ISC_MEMFLAG_DEFAULT 	ISC_MEMFLAG_INTERNAL
#else
#define ISC_MEMFLAG_DEFAULT 	0
#endif

146

147 148 149 150 151 152 153 154 155 156
/*%<
 * We use either isc___mem (three underscores) or isc__mem (two) depending on
 * whether it's for BIND9's internal purpose (with -DBIND9) or generic export
 * library.  This condition is generally handled in isc/namespace.h, but for
 * Windows it doesn't work if it involves multiple times of macro expansion
 * (such as isc_mem to isc__mem then to isc___mem).  The following definitions
 * are used to work around this portability issue.  Right now, we don't support
 * the export library for Windows, so we always use the three-underscore
 * version.
 */
157 158 159 160 161 162 163 164 165 166 167 168 169
#ifdef WIN32
#define ISCMEMFUNC(sfx) isc___mem_ ## sfx
#define ISCMEMPOOLFUNC(sfx) isc___mempool_ ## sfx
#else
#define ISCMEMFUNC(sfx) isc__mem_ ## sfx
#define ISCMEMPOOLFUNC(sfx) isc__mempool_ ## sfx
#endif

#define isc_mem_get(c, s)	ISCMEMFUNC(get)((c), (s) _ISC_MEM_FILELINE)
#define isc_mem_allocate(c, s)	ISCMEMFUNC(allocate)((c), (s) _ISC_MEM_FILELINE)
#define isc_mem_reallocate(c, p, s) ISCMEMFUNC(reallocate)((c), (p), (s) _ISC_MEM_FILELINE)
#define isc_mem_strdup(c, p)	ISCMEMFUNC(strdup)((c), (p) _ISC_MEM_FILELINE)
#define isc_mempool_get(c)	ISCMEMPOOLFUNC(get)((c) _ISC_MEM_FILELINE)
170

Automatic Updater's avatar
Automatic Updater committed
171
/*%
Francis Dupont's avatar
Francis Dupont committed
172
 * isc_mem_putanddetach() is a convenience function for use where you
173 174 175 176
 * have a structure with an attached memory context.
 *
 * Given:
 *
177
 * \code
178 179 180 181 182 183 184 185 186
 * struct {
 *	...
 *	isc_mem_t *mctx;
 *	...
 * } *ptr;
 *
 * isc_mem_t *mctx;
 *
 * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr));
187
 * \endcode
188 189 190
 *
 * is the equivalent of:
 *
191
 * \code
192 193 194 195 196
 * mctx = NULL;
 * isc_mem_attach(ptr->mctx, &mctx);
 * isc_mem_detach(&ptr->mctx);
 * isc_mem_put(mctx, ptr, sizeof(*ptr));
 * isc_mem_detach(&mctx);
197
 * \endcode
198 199
 */

200 201 202 203 204 205 206 207 208 209
/*% memory and memory pool methods */
typedef struct isc_memmethods {
	void (*attach)(isc_mem_t *source, isc_mem_t **targetp);
	void (*detach)(isc_mem_t **mctxp);
	void (*destroy)(isc_mem_t **mctxp);
	void *(*memget)(isc_mem_t *mctx, size_t size _ISC_MEM_FLARG);
	void (*memput)(isc_mem_t *mctx, void *ptr, size_t size _ISC_MEM_FLARG);
	void (*memputanddetach)(isc_mem_t **mctxp, void *ptr,
				size_t size _ISC_MEM_FLARG);
	void *(*memallocate)(isc_mem_t *mctx, size_t size _ISC_MEM_FLARG);
210 211
	void *(*memreallocate)(isc_mem_t *mctx, void *ptr,
			       size_t size _ISC_MEM_FLARG);
212 213 214 215 216 217 218
	char *(*memstrdup)(isc_mem_t *mctx, const char *s _ISC_MEM_FLARG);
	void (*memfree)(isc_mem_t *mctx, void *ptr _ISC_MEM_FLARG);
	void (*setdestroycheck)(isc_mem_t *mctx, isc_boolean_t flag);
	void (*setwater)(isc_mem_t *ctx, isc_mem_water_t water,
			 void *water_arg, size_t hiwater, size_t lowater);
	void (*waterack)(isc_mem_t *ctx, int flag);
	size_t (*inuse)(isc_mem_t *mctx);
219 220
	size_t (*maxinuse)(isc_mem_t *mctx);
	size_t (*total)(isc_mem_t *mctx);
221
	isc_boolean_t (*isovermem)(isc_mem_t *mctx);
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238
	isc_result_t (*mpcreate)(isc_mem_t *mctx, size_t size,
				 isc_mempool_t **mpctxp);
} isc_memmethods_t;

typedef struct isc_mempoolmethods {
	void (*destroy)(isc_mempool_t **mpctxp);
	void *(*get)(isc_mempool_t *mpctx _ISC_MEM_FLARG);
	void (*put)(isc_mempool_t *mpctx, void *mem _ISC_MEM_FLARG);
	unsigned int (*getallocated)(isc_mempool_t *mpctx);
	void (*setmaxalloc)(isc_mempool_t *mpctx, unsigned int limit);
	void (*setfreemax)(isc_mempool_t *mpctx, unsigned int limit);
	void (*setname)(isc_mempool_t *mpctx, const char *name);
	void (*associatelock)(isc_mempool_t *mpctx, isc_mutex_t *lock);
	void (*setfillcount)(isc_mempool_t *mpctx, unsigned int limit);
} isc_mempoolmethods_t;

/*%
Automatic Updater's avatar
Automatic Updater committed
239
 * This structure is actually just the common prefix of a memory context
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270
 * implementation's version of an isc_mem_t.
 * \brief
 * Direct use of this structure by clients is forbidden.  mctx implementations
 * may change the structure.  'magic' must be ISCAPI_MCTX_MAGIC for any of the
 * isc_mem_ routines to work.  mctx implementations must maintain all mctx
 * invariants.
 */
struct isc_mem {
	unsigned int		impmagic;
	unsigned int		magic;
	isc_memmethods_t	*methods;
};

#define ISCAPI_MCTX_MAGIC	ISC_MAGIC('A','m','c','x')
#define ISCAPI_MCTX_VALID(m)	((m) != NULL && \
				 (m)->magic == ISCAPI_MCTX_MAGIC)

/*%
 * This is the common prefix of a memory pool context.  The same note as
 * that for the mem structure applies.
 */
struct isc_mempool {
	unsigned int		impmagic;
	unsigned int		magic;
	isc_mempoolmethods_t	*methods;
};

#define ISCAPI_MPOOL_MAGIC	ISC_MAGIC('A','m','p','l')
#define ISCAPI_MPOOL_VALID(mp)	((mp) != NULL && \
				 (mp)->magic == ISCAPI_MPOOL_MAGIC)

Michael Graff's avatar
Michael Graff committed
271 272
#define isc_mem_put(c, p, s) \
	do { \
273
		ISCMEMFUNC(put)((c), (p), (s) _ISC_MEM_FILELINE);	\
Michael Graff's avatar
Michael Graff committed
274 275
		(p) = NULL; \
	} while (0)
276 277
#define isc_mem_putanddetach(c, p, s) \
	do { \
278
		ISCMEMFUNC(putanddetach)((c), (p), (s) _ISC_MEM_FILELINE); \
279 280
		(p) = NULL; \
	} while (0)
Michael Graff's avatar
Michael Graff committed
281 282
#define isc_mem_free(c, p) \
	do { \
283
		ISCMEMFUNC(free)((c), (p) _ISC_MEM_FILELINE);	\
Michael Graff's avatar
Michael Graff committed
284 285 286 287
		(p) = NULL; \
	} while (0)
#define isc_mempool_put(c, p) \
	do { \
288
		ISCMEMPOOLFUNC(put)((c), (p) _ISC_MEM_FILELINE);	\
Michael Graff's avatar
Michael Graff committed
289 290
		(p) = NULL; \
	} while (0)
Bob Halley's avatar
update  
Bob Halley committed
291

292
/*@{*/
Automatic Updater's avatar
Automatic Updater committed
293
isc_result_t
294
isc_mem_create(size_t max_size, size_t target_size,
295
	       isc_mem_t **mctxp);
296

297 298 299 300
isc_result_t
isc_mem_create2(size_t max_size, size_t target_size,
		isc_mem_t **mctxp, unsigned int flags);

Automatic Updater's avatar
Automatic Updater committed
301
isc_result_t
302
isc_mem_createx(size_t max_size, size_t target_size,
303 304
		isc_memalloc_t memalloc, isc_memfree_t memfree,
		void *arg, isc_mem_t **mctxp);
305

Automatic Updater's avatar
Automatic Updater committed
306
isc_result_t
307 308 309 310
isc_mem_createx2(size_t max_size, size_t target_size,
		 isc_memalloc_t memalloc, isc_memfree_t memfree,
		 void *arg, isc_mem_t **mctxp, unsigned int flags);

311 312
/*!<
 * \brief Create a memory context.
313
 *
314
 * 'max_size' and 'target_size' are tuning parameters.  When
315 316 317 318 319 320
 * ISC_MEMFLAG_INTERNAL is set, allocations smaller than 'max_size'
 * will be satisfied by getting blocks of size 'target_size' from the
 * system allocator and breaking them up into pieces; larger allocations
 * will use the system allocator directly. If 'max_size' and/or
 * 'target_size' are zero, default values will be * used.  When
 * ISC_MEMFLAG_INTERNAL is not set, 'target_size' is ignored.
321 322
 *
 * 'max_size' is also used to size the statistics arrays and the array
Francis Dupont's avatar
Francis Dupont committed
323
 * used to record active memory when ISC_MEM_DEBUGRECORD is set.  Setting
324
 * 'max_size' too low can have detrimental effects on performance.
325 326 327 328 329 330 331
 *
 * A memory context created using isc_mem_createx() will obtain
 * memory from the system by calling 'memalloc' and 'memfree',
 * passing them the argument 'arg'.  A memory context created
 * using isc_mem_create() will use the standard library malloc()
 * and free().
 *
332 333 334 335 336 337
 * If ISC_MEMFLAG_NOLOCK is set in 'flags', the corresponding memory context
 * will be accessed without locking.  The user who creates the context must
 * ensure there be no race.  Since this can be a source of bug, it is generally
 * inadvisable to use this flag unless the user is very sure about the race
 * condition and the access to the object is highly performance sensitive.
 *
338
 * Requires:
339
 * mctxp != NULL && *mctxp == NULL */
340
/*@}*/
341

342
/*@{*/
Automatic Updater's avatar
Automatic Updater committed
343
void
344
isc_mem_attach(isc_mem_t *, isc_mem_t **);
Automatic Updater's avatar
Automatic Updater committed
345
void
346
isc_mem_detach(isc_mem_t **);
347 348
/*!<
 * \brief Attach to / detach from a memory context.
349 350 351 352
 *
 * This is intended for applications that use multiple memory contexts
 * in such a way that it is not obvious when the last allocations from
 * a given context has been freed and destroying the context is safe.
Automatic Updater's avatar
Automatic Updater committed
353
 *
354 355 356 357 358
 * Most applications do not need to call these functions as they can
 * simply create a single memory context at the beginning of main()
 * and destroy it at the end of main(), thereby guaranteeing that it
 * is not destroyed while there are outstanding allocations.
 */
359
/*@}*/
360

Automatic Updater's avatar
Automatic Updater committed
361
void
362
isc_mem_destroy(isc_mem_t **);
363
/*%<
364 365 366
 * Destroy a memory context.
 */

Automatic Updater's avatar
Automatic Updater committed
367
isc_result_t
368
isc_mem_ondestroy(isc_mem_t *ctx,
369 370
		  isc_task_t *task,
		  isc_event_t **event);
371
/*%<
372 373 374 375
 * Request to be notified with an event when a memory context has
 * been successfully destroyed.
 */

Automatic Updater's avatar
Automatic Updater committed
376
void
377
isc_mem_stats(isc_mem_t *mctx, FILE *out);
378
/*%<
379 380 381
 * Print memory usage statistics for 'mctx' on the stream 'out'.
 */

Automatic Updater's avatar
Automatic Updater committed
382
void
383
isc_mem_setdestroycheck(isc_mem_t *mctx,
384
			isc_boolean_t on);
385 386
/*%<
 * If 'on' is ISC_TRUE, 'mctx' will check for memory leaks when
387 388 389
 * destroyed and abort the program if any are present.
 */

390
/*@{*/
Automatic Updater's avatar
Automatic Updater committed
391
void
392
isc_mem_setquota(isc_mem_t *, size_t);
Automatic Updater's avatar
Automatic Updater committed
393
size_t
394
isc_mem_getquota(isc_mem_t *);
395
/*%<
396 397 398 399
 * Set/get the memory quota of 'mctx'.  This is a hard limit
 * on the amount of memory that may be allocated from mctx;
 * if it is exceeded, allocations will fail.
 */
400
/*@}*/
401

Automatic Updater's avatar
Automatic Updater committed
402
size_t
403
isc_mem_inuse(isc_mem_t *mctx);
404
/*%<
405
 * Get an estimate of the amount of memory in use in 'mctx', in bytes.
406 407 408 409
 * This includes quantization overhead, but does not include memory
 * allocated from the system but not yet used.
 */

410 411 412 413 414 415 416 417 418 419 420 421 422 423
size_t
isc_mem_maxinuse(isc_mem_t *mctx);
/*%<
 * Get an estimate of the largest amount of memory that has been in
 * use in 'mctx' at any time.
 */

size_t
isc_mem_total(isc_mem_t *mctx);
/*%<
 * Get the total amount of memory in 'mctx', in bytes, including memory
 * not yet used.
 */

424 425 426 427 428 429 430 431
isc_boolean_t
isc_mem_isovermem(isc_mem_t *mctx);
/*%<
 * Return true iff the memory context is in "over memory" state, i.e.,
 * a hiwater mark has been set and the used amount of memory has exceeds
 * the mark.
 */

432 433 434
void
isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
		 size_t hiwater, size_t lowater);
435
/*%<
Automatic Updater's avatar
Automatic Updater committed
436 437
 * Set high and low water marks for this memory context.
 *
438 439
 * When the memory usage of 'mctx' exceeds 'hiwater',
 * '(water)(water_arg, #ISC_MEM_HIWATER)' will be called.  'water' needs to
Francis Dupont's avatar
Francis Dupont committed
440
 * call isc_mem_waterack() with #ISC_MEM_HIWATER to acknowledge the state
441 442 443 444
 * change.  'water' may be called multiple times.
 *
 * When the usage drops below 'lowater', 'water' will again be called, this
 * time with #ISC_MEM_LOWATER.  'water' need to calls isc_mem_waterack() with
Francis Dupont's avatar
Francis Dupont committed
445
 * #ISC_MEM_LOWATER to acknowledge the change.
446 447 448
 *
 *	static void
 *	water(void *arg, int mark) {
Mark Andrews's avatar
Mark Andrews committed
449
 *		struct foo *foo = arg;
450 451 452 453 454 455 456 457 458
 *
 *		LOCK(&foo->marklock);
 *		if (foo->mark != mark) {
 * 			foo->mark = mark;
 *			....
 *			isc_mem_waterack(foo->mctx, mark);
 *		}
 *		UNLOCK(&foo->marklock);
 *	}
459
 *
460 461 462
 * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
 * ignored and the state is reset.
 *
463
 * Requires:
Andreas Gustafsson's avatar
Andreas Gustafsson committed
464
 *
465 466
 *	'water' is not NULL.
 *	hi_water >= lo_water
467 468
 */

469 470 471
void
isc_mem_waterack(isc_mem_t *ctx, int mark);
/*%<
Francis Dupont's avatar
Francis Dupont committed
472
 * Called to acknowledge changes in signaled by calls to 'water'.
473 474
 */

475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498
void
isc_mem_printactive(isc_mem_t *mctx, FILE *file);
/*%<
 * Print to 'file' all active memory in 'mctx'.
 *
 * Requires ISC_MEM_DEBUGRECORD to have been set.
 */

void
isc_mem_printallactive(FILE *file);
/*%<
 * Print to 'file' all active memory in all contexts.
 *
 * Requires ISC_MEM_DEBUGRECORD to have been set.
 */

void
isc_mem_checkdestroyed(FILE *file);
/*%<
 * Check that all memory contexts have been destroyed.
 * Prints out those that have not been.
 * Fatally fails if there are still active contexts.
 */

499 500 501 502 503 504
unsigned int
isc_mem_references(isc_mem_t *ctx);
/*%<
 * Return the current reference count.
 */

505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550
void
isc_mem_setname(isc_mem_t *ctx, const char *name, void *tag);
/*%<
 * Name 'ctx'.
 *
 * Notes:
 *
 *\li	Only the first 15 characters of 'name' will be copied.
 *
 *\li	'tag' is for debugging purposes only.
 *
 * Requires:
 *
 *\li	'ctx' is a valid ctx.
 */

const char *
isc_mem_getname(isc_mem_t *ctx);
/*%<
 * Get the name of 'ctx', as previously set using isc_mem_setname().
 *
 * Requires:
 *\li	'ctx' is a valid ctx.
 *
 * Returns:
 *\li	A non-NULL pointer to a null-terminated string.
 * 	If the ctx has not been named, the string is
 * 	empty.
 */

void *
isc_mem_gettag(isc_mem_t *ctx);
/*%<
 * Get the tag value for  'task', as previously set using isc_mem_setname().
 *
 * Requires:
 *\li	'ctx' is a valid ctx.
 *
 * Notes:
 *\li	This function is for debugging purposes only.
 *
 * Requires:
 *\li	'ctx' is a valid task.
 */

#ifdef HAVE_LIBXML2
Mark Andrews's avatar
Mark Andrews committed
551
int
552 553 554 555 556 557
isc_mem_renderxml(xmlTextWriterPtr writer);
/*%<
 * Render all contexts' statistics and status in XML for writer.
 */
#endif /* HAVE_LIBXML2 */

558 559 560 561 562 563 564 565 566
#ifdef HAVE_JSON
isc_result_t
isc_mem_renderjson(json_object *memobj);
/*%<
 * Render all contexts' statistics and status in JSON.
 */
#endif /* HAVE_JSON */


Michael Graff's avatar
Michael Graff committed
567 568 569
/*
 * Memory pools
 */
Michael Graff's avatar
Michael Graff committed
570

Michael Graff's avatar
Michael Graff committed
571 572
isc_result_t
isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
573
/*%<
Michael Graff's avatar
Michael Graff committed
574 575 576
 * Create a memory pool.
 *
 * Requires:
577 578 579
 *\li	mctx is a valid memory context.
 *\li	size > 0
 *\li	mpctxp != NULL and *mpctxp == NULL
Michael Graff's avatar
Michael Graff committed
580 581
 *
 * Defaults:
582 583 584
 *\li	maxalloc = UINT_MAX
 *\li	freemax = 1
 *\li	fillcount = 1
Michael Graff's avatar
Michael Graff committed
585 586
 *
 * Returns:
587 588
 *\li	#ISC_R_NOMEMORY		-- not enough memory to create pool
 *\li	#ISC_R_SUCCESS		-- all is well.
Michael Graff's avatar
Michael Graff committed
589 590
 */

Michael Graff's avatar
Michael Graff committed
591 592
void
isc_mempool_destroy(isc_mempool_t **mpctxp);
593
/*%<
Michael Graff's avatar
Michael Graff committed
594 595 596
 * Destroy a memory pool.
 *
 * Requires:
597 598
 *\li	mpctxp != NULL && *mpctxp is a valid pool.
 *\li	The pool has no un"put" allocations outstanding
Michael Graff's avatar
Michael Graff committed
599 600
 */

Michael Graff's avatar
Michael Graff committed
601
void
David Lawrence's avatar
David Lawrence committed
602
isc_mempool_setname(isc_mempool_t *mpctx, const char *name);
603
/*%<
Michael Graff's avatar
Michael Graff committed
604 605 606
 * Associate a name with a memory pool.  At most 15 characters may be used.
 *
 * Requires:
607 608
 *\li	mpctx is a valid pool.
 *\li	name != NULL;
Michael Graff's avatar
Michael Graff committed
609 610
 */

Michael Graff's avatar
Michael Graff committed
611 612
void
isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
613
/*%<
Michael Graff's avatar
Michael Graff committed
614 615 616 617 618 619
 * Associate a lock with this memory pool.
 *
 * This lock is used when getting or putting items using this memory pool,
 * and it is also used to set or get internal state via the isc_mempool_get*()
 * and isc_mempool_set*() set of functions.
 *
Francis Dupont's avatar
Francis Dupont committed
620
 * Multiple pools can each share a single lock.  For instance, if "manager"
Michael Graff's avatar
Michael Graff committed
621 622 623 624 625 626 627
 * type object contained pools for various sizes of events, and each of
 * these pools used a common lock.  Note that this lock must NEVER be used
 * by other than mempool routines once it is given to a pool, since that can
 * easily cause double locking.
 *
 * Requires:
 *
628
 *\li	mpctpx is a valid pool.
Michael Graff's avatar
Michael Graff committed
629
 *
630
 *\li	lock != NULL.
Michael Graff's avatar
Michael Graff committed
631
 *
632
 *\li	No previous lock is assigned to this pool.
Michael Graff's avatar
Michael Graff committed
633
 *
634
 *\li	The lock is initialized before calling this function via the normal
Michael Graff's avatar
Michael Graff committed
635 636
 *	means of doing that.
 */
Michael Graff's avatar
Michael Graff committed
637 638 639 640 641 642 643

/*
 * The following functions get/set various parameters.  Note that due to
 * the unlocked nature of pools these are potentially random values unless
 * the imposed externally provided locking protocols are followed.
 *
 * Also note that the quota limits will not always take immediate effect.
Michael Graff's avatar
Michael Graff committed
644
 * For instance, setting "maxalloc" to a number smaller than the currently
Michael Graff's avatar
Michael Graff committed
645 646 647 648 649 650 651
 * allocated count is permitted.  New allocations will be refused until
 * the count drops below this threshold.
 *
 * All functions require (in addition to other requirements):
 *	mpctx is a valid memory pool
 */

652 653
unsigned int
isc_mempool_getfreemax(isc_mempool_t *mpctx);
654
/*%<
Michael Graff's avatar
Michael Graff committed
655 656 657
 * Returns the maximum allowed size of the free list.
 */

658 659
void
isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
660
/*%<
Michael Graff's avatar
Michael Graff committed
661 662 663
 * Sets the maximum allowed size of the free list.
 */

664 665
unsigned int
isc_mempool_getfreecount(isc_mempool_t *mpctx);
666
/*%<
Michael Graff's avatar
Michael Graff committed
667 668 669
 * Returns current size of the free list.
 */

670 671
unsigned int
isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
672
/*!<
Michael Graff's avatar
Michael Graff committed
673 674 675
 * Returns the maximum allowed number of allocations.
 */

676 677
void
isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
678
/*%<
Michael Graff's avatar
Michael Graff committed
679 680 681
 * Sets the maximum allowed number of allocations.
 *
 * Additional requirements:
682
 *\li	limit > 0
Michael Graff's avatar
Michael Graff committed
683 684
 */

685 686
unsigned int
isc_mempool_getallocated(isc_mempool_t *mpctx);
687
/*%<
Michael Graff's avatar
Michael Graff committed
688 689 690
 * Returns the number of items allocated from this pool.
 */

691 692
unsigned int
isc_mempool_getfillcount(isc_mempool_t *mpctx);
693
/*%<
Michael Graff's avatar
Michael Graff committed
694 695 696 697
 * Returns the number of items allocated as a block from the parent memory
 * context when the free list is empty.
 */

698 699
void
isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
700
/*%<
Michael Graff's avatar
Michael Graff committed
701 702 703
 * Sets the fillcount.
 *
 * Additional requirements:
704
 *\li	limit > 0
Michael Graff's avatar
Michael Graff committed
705
 */
Michael Graff's avatar
Michael Graff committed
706

707 708 709 710

/*
 * Pseudo-private functions for use via macros.  Do not call directly.
 */
Automatic Updater's avatar
Automatic Updater committed
711
void *
712
ISCMEMFUNC(get)(isc_mem_t *, size_t _ISC_MEM_FLARG);
Automatic Updater's avatar
Automatic Updater committed
713
void
714
ISCMEMFUNC(putanddetach)(isc_mem_t **, void *, size_t _ISC_MEM_FLARG);
Automatic Updater's avatar
Automatic Updater committed
715
void
716
ISCMEMFUNC(put)(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
Automatic Updater's avatar
Automatic Updater committed
717
void *
718
ISCMEMFUNC(allocate)(isc_mem_t *, size_t _ISC_MEM_FLARG);
719
void *
720
ISCMEMFUNC(reallocate)(isc_mem_t *, void *, size_t _ISC_MEM_FLARG);
Automatic Updater's avatar
Automatic Updater committed
721
void
722
ISCMEMFUNC(free)(isc_mem_t *, void * _ISC_MEM_FLARG);
Automatic Updater's avatar
Automatic Updater committed
723
char *
724
ISCMEMFUNC(strdup)(isc_mem_t *, const char *_ISC_MEM_FLARG);
Automatic Updater's avatar
Automatic Updater committed
725
void *
726
ISCMEMPOOLFUNC(get)(isc_mempool_t * _ISC_MEM_FLARG);
Automatic Updater's avatar
Automatic Updater committed
727
void
728
ISCMEMPOOLFUNC(put)(isc_mempool_t *, void * _ISC_MEM_FLARG);
729

730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756
#ifdef USE_MEMIMPREGISTER

/*%<
 * See isc_mem_create2() above.
 */
typedef isc_result_t
(*isc_memcreatefunc_t)(size_t init_max_size, size_t target_size,
		       isc_mem_t **ctxp, unsigned int flags);

isc_result_t
isc_mem_register(isc_memcreatefunc_t createfunc);
/*%<
 * Register a new memory management implementation and add it to the list of
 * supported implementations.  This function must be called when a different
 * memory management library is used than the one contained in the ISC library.
 */

isc_result_t
isc__mem_register(void);
/*%<
 * A short cut function that specifies the memory management module in the ISC
 * library for isc_mem_register().  An application that uses the ISC library
 * usually do not have to care about this function: it would call
 * isc_lib_register(), which internally calls this function.
 */
#endif /* USE_MEMIMPREGISTER */

Bob Halley's avatar
Bob Halley committed
757 758
ISC_LANG_ENDDECLS

759
#endif /* ISC_MEM_H */