mem.h revision 3a34b87c878990c6303358efd22265c2c5980c65
49dbdb0186eb23d87d685b96eaefa9ec3c71d9b8David Lawrence * Copyright (C) 1997-2000 Internet Software Consortium.
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * Permission to use, copy, modify, and distribute this software for any
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * purpose with or without fee is hereby granted, provided that the above
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * copyright notice and this permission notice appear in all copies.
15a44745412679c30a6d022733925af70a38b715David Lawrence * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
15a44745412679c30a6d022733925af70a38b715David Lawrence * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
15a44745412679c30a6d022733925af70a38b715David Lawrence * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
15a44745412679c30a6d022733925af70a38b715David Lawrence * INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
15a44745412679c30a6d022733925af70a38b715David Lawrence * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
15a44745412679c30a6d022733925af70a38b715David Lawrence * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
15a44745412679c30a6d022733925af70a38b715David Lawrence * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
15a44745412679c30a6d022733925af70a38b715David Lawrence * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews/* $Id: mem.h,v 1.41 2000/08/31 12:15:17 marka Exp $ */
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrewstypedef void (*isc_mem_water_t)(void *, int);
ac70da9a2710aa9f343d2f720eb1bdd4191a79caBob Halleytypedef void (*isc_memfree_t)(void *, void *);
de88422aec961bcda8b383b4a4327180584ca993David Lawrence * ISC_MEM_DEBUG is defined by default; define ISC_MEM_DEBUGOFF to disable it.
de88422aec961bcda8b383b4a4327180584ca993David Lawrence#if !defined(ISC_MEM_DEBUG) && !defined(ISC_MEM_DEBUGOFF)
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * Define ISC_MEM_TRACKLINES to turn on detailed tracing of memory allocation
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * and freeing by file and line number.
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * Define ISC_MEM_CHECKOVERRUN to turn on checks for using memory outside
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * the requested space. This will increase the size of each allocation.
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * Define ISC_MEM_FILL to fill each block of memory returned to the system
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * with the byte string '0xbe'. This helps track down uninitialized pointers
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * and the like. On freeing memory, the space is filled with '0xde' for
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * the same reasons.
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * Define this to turn on memory pool names.
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * _DEBUGTRACE
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * log (to isc_lctx) each allocation and free.
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * _DEBUGRECORD
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * remember each allocation, and match them up on free. Crash if
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff * a free doesn't match an allocation
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graffextern unsigned int isc_mem_debugging;
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define _ISC_MEM_FLARG , const char *, int
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define isc_mem_get(c, s) isc__mem_get((c), (s) _ISC_MEM_FILELINE)
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define isc_mem_allocate(c, s) isc__mem_allocate((c), (s) _ISC_MEM_FILELINE)
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define isc_mem_strdup(c, p) isc__mem_strdup((c), (p) _ISC_MEM_FILELINE)
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define isc_mempool_get(c) isc__mempool_get((c) _ISC_MEM_FILELINE)
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define isc_mem_put(c, p, s) \
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE); \
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff isc__mempool_put((c), (p) _ISC_MEM_FILELINE); \
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define isc_mem_put(c, p, s) isc__mem_put((c), (p), (s) _ISC_MEM_FILELINE)
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define isc_mem_free(c, p) isc__mem_free((c), (p) _ISC_MEM_FILELINE)
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graff#define isc_mempool_put(c, p) isc__mempool_put((c), (p) _ISC_MEM_FILELINE)
4cafb28abcaa2a485c7aac1696213435538b92edBob Halleyisc_result_t isc_mem_create(size_t, size_t, isc_mem_t **);
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graffchar * isc__mem_strdup(isc_mem_t *, const char *
fd3271152c6a2ff54348ae9f5369f0962fcc89b6Bob Halleyvoid isc_mem_setsplit(isc_mem_t *, isc_boolean_t);
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrewsisc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg,
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * Set high and low water marks for this memory context. When the memory
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * usage of 'mctx' exceeds 'hiwater', '(water)(water_arg, ISC_MEM_HIWATER)'
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * will be called. When the usage drops below 'lowater', 'water' will
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * again be called, this time with ISC_MEM_LOWATER.
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * ignored and the state is reset otherwise.
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * 'water' to point to a valid function.
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * 'hi_water > lo_water'
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * 'lo_water != 0'
3a34b87c878990c6303358efd22265c2c5980c65Mark Andrews * 'hi_water != 0'
eb7ef395d27b1104f684e21836f200c052736d07Michael Graff * Memory pools
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Internal (but public) functions. Don't call these from application
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * code. Use isc_mempool_get() and isc_mempool_put() instead.
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graffvoid * isc__mempool_get(isc_mempool_t * _ISC_MEM_FLARG);
bfab56849df65a2d4295b256808a66985cfa9d98Michael Graffvoid isc__mempool_put(isc_mempool_t *, void * _ISC_MEM_FLARG);
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graffisc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Create a memory pool.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * mctx is a valid memory context.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * mpctxp != NULL and *mpctxp == NULL
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * maxalloc = UINT_MAX
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * freemax = 1
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * fillcount = 1
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * ISC_R_NOMEMORY -- not enough memory to create pool
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * ISC_R_SUCCESS -- all is well.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Destroy a memory pool.
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * mpctxp != NULL && *mpctxp is a valid pool.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * The pool has no un"put" allocations outstanding
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrenceisc_mempool_setname(isc_mempool_t *mpctx, const char *name);
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * Associate a name with a memory pool. At most 15 characters may be used.
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * mpctx is a valid pool.
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * name != NULL;
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graffisc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * Associate a lock with this memory pool.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * This lock is used when getting or putting items using this memory pool,
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * and it is also used to set or get internal state via the isc_mempool_get*()
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * and isc_mempool_set*() set of functions.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * Mutiple pools can each share a single lock. For instance, if "manager"
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * type object contained pools for various sizes of events, and each of
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * these pools used a common lock. Note that this lock must NEVER be used
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * by other than mempool routines once it is given to a pool, since that can
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * easily cause double locking.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * mpctpx is a valid pool.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * lock != NULL.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * No previous lock is assigned to this pool.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * The lock is initialized before calling this function via the normal
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * means of doing that.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * The following functions get/set various parameters. Note that due to
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * the unlocked nature of pools these are potentially random values unless
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * the imposed externally provided locking protocols are followed.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Also note that the quota limits will not always take immediate effect.
0fd03d2a66102f8d9bd7acea4e7db73ecaa0cb52Michael Graff * For instance, setting "maxalloc" to a number smaller than the currently
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * allocated count is permitted. New allocations will be refused until
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * the count drops below this threshold.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * All functions require (in addition to other requirements):
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * mpctx is a valid memory pool
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns the maximum allowed size of the free list.
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceisc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Sets the maximum allowed size of the free list.
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceisc_mempool_getfreecount(isc_mempool_t *mpctx);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns current size of the free list.
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceisc_mempool_getmaxalloc(isc_mempool_t *mpctx);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns the maximum allowed number of allocations.
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceisc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Sets the maximum allowed number of allocations.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Additional requirements:
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceisc_mempool_getallocated(isc_mempool_t *mpctx);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns the number of items allocated from this pool.
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceisc_mempool_getfillcount(isc_mempool_t *mpctx);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns the number of items allocated as a block from the parent memory
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * context when the free list is empty.
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceisc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Sets the fillcount.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Additional requirements:
54a2e7e8a21ee765f41bd995101995613bff9e8cDavid Lawrence#endif /* ISC_MEM_H */