mem.h revision 78b2f25c9afee0d16f2e75882d9763abcb0872e5
ca41b452ede6feaa9d8739ec3cae19389a7b0d03Bob Halley * Copyright (C) 1997, 1998, 1999 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.
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
669940866360b2e50eed04f18f58ca7fe302c8baBob Halleytypedef void (*isc_memfree_t)(void *, void *);
5f89718b7d354cb4ceb99d0dd952a4faf4597ab8David Lawrence * Define to 0 to remove the names from memory pools. This will save
669940866360b2e50eed04f18f58ca7fe302c8baBob Halley * about 16 bytes per pool.
eb7ef395d27b1104f684e21836f200c052736d07Michael Graff#define isc_mem_get(c, s) __isc_mem_getdebug(c, s, __FILE__, __LINE__)
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley#define isc_mem_put(c, p, s) __isc_mem_putdebug(c, p, s, __FILE__, __LINE__)
669940866360b2e50eed04f18f58ca7fe302c8baBob Halley#define isc_mempool_get(c) __isc_mempool_getdebug(c, __FILE__, __LINE__)
669940866360b2e50eed04f18f58ca7fe302c8baBob Halley#define isc_mempool_put(c, p) __isc_mempool_putdebug(c, p, \
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley#endif /* ISC_MEM_DEBUG */
fd3271152c6a2ff54348ae9f5369f0962fcc89b6Bob Halleyisc_result_t isc_mem_create(size_t, size_t, isc_mem_t **);
80d19f35232dfcb37a38d80fd7c0a9f755c91320James Bristervoid __isc_mem_put(isc_mem_t *, void *, size_t);
80d19f35232dfcb37a38d80fd7c0a9f755c91320James Brister const char *, int);
669940866360b2e50eed04f18f58ca7fe302c8baBob Halley size_t, const char *, int);
4cafb28abcaa2a485c7aac1696213435538b92edBob Halleyisc_boolean_t isc_mem_destroy_check(isc_mem_t *, isc_boolean_t);
ac70da9a2710aa9f343d2f720eb1bdd4191a79caBob Halley#define memget(s) __memget_debug(s, __FILE__, __LINE__)
ac70da9a2710aa9f343d2f720eb1bdd4191a79caBob Halley#define memput(p, s) __memput_debug(p, s, __FILE__, __LINE__)
6d8cdbaff46ea186ddc83ba9484f453a34645d8bDavid Lawrencevoid * __memget_debug(size_t, const char *, int);
6d8cdbaff46ea186ddc83ba9484f453a34645d8bDavid Lawrence#endif /* ISC_MEMCLUSTER_LEGACY */
6d8cdbaff46ea186ddc83ba9484f453a34645d8bDavid Lawrence * Memory pools
4cafb28abcaa2a485c7aac1696213435538b92edBob Halley * Internal (but public) functions. Don't call these from application
6d8cdbaff46ea186ddc83ba9484f453a34645d8bDavid Lawrence * code. Use isc_mempool_get() and isc_mempool_put() instead.
6d8cdbaff46ea186ddc83ba9484f453a34645d8bDavid Lawrencevoid __isc_mempool_put(isc_mempool_t *, void *);
6d8cdbaff46ea186ddc83ba9484f453a34645d8bDavid Lawrencevoid * __isc_mempool_getdebug(isc_mempool_t *, const char *, int);
6d8cdbaff46ea186ddc83ba9484f453a34645d8bDavid Lawrencevoid __isc_mempool_putdebug(isc_mempool_t *, void *,
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley const char *, int);
de9282a1eaa50764fdc2e88046f8ff3522e3092eBob Halleyisc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp);
eb7ef395d27b1104f684e21836f200c052736d07Michael Graff * Create a memory pool.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * mctx is a valid memory context.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * mpctxp != NULL and *mpctxp == NULL
669940866360b2e50eed04f18f58ca7fe302c8baBob Halley * maxalloc = UINT_MAX
669940866360b2e50eed04f18f58ca7fe302c8baBob Halley * freemax = 1
669940866360b2e50eed04f18f58ca7fe302c8baBob Halley * fillcount = 1
eb7ef395d27b1104f684e21836f200c052736d07Michael Graff * ISC_R_NOMEMORY -- not enough memory to create pool
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * ISC_R_SUCCESS -- all is well.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Destroy a memory pool.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * mpctxp != NULL && *mpctxp is a valid pool.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * The pool has no un"put" allocations outstanding
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffisc_mempool_setname(isc_mempool_t *mpctx, char *name);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Associate a name with a memory pool. At most 15 characters may be used.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * mpctx is a valid pool.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * name != NULL;
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffisc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock);
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * Associate a lock with this memory pool.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * This lock is used when getting or putting items using this memory pool,
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * and it is also used to set or get internal state via the isc_mempool_get*()
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * and isc_mempool_set*() set of functions.
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * Mutiple pools can each share a single lock. For instance, if "manager"
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * type object contained pools for various sizes of events, and each of
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * these pools used a common lock. Note that this lock must NEVER be used
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * by other than mempool routines once it is given to a pool, since that can
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael 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.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * The following functions get/set various parameters. Note that due to
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * the unlocked nature of pools these are potentially random values unless
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * the imposed externally provided locking protocols are followed.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * Also note that the quota limits will not always take immediate effect.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * For instance, setting "maxalloc" to a number larger than the currently
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * allocated count is permitted. New allocations will be refused until
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * the count drops below this threshold.
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * All functions require (in addition to other requirements):
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graff * mpctx is a valid memory pool
50dfb7ee4ada4c9aa30bd18c1b5d9b04be765669Michael Graffunsigned int isc_mempool_getfreemax(isc_mempool_t *mpctx);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns the maximum allowed size of the free list.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffvoid isc_mempool_setfreemax(isc_mempool_t *mpctx,
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff unsigned int limit);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Sets the maximum allowed size of the free list.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffunsigned int isc_mempool_getfreecount(isc_mempool_t *mpctx);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns current size of the free list.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffunsigned int isc_mempool_getmaxalloc(isc_mempool_t *mpctx);
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrence * Returns the maximum allowed number of allocations.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffvoid isc_mempool_setmaxalloc(isc_mempool_t *mpctx,
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff unsigned int limit);
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrence * Sets the maximum allowed number of allocations.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Additional requirements:
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceunsigned int isc_mempool_getallocated(isc_mempool_t *mpctx);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns the number of items allocated from this pool.
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrenceunsigned int isc_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 Lawrencevoid isc_mempool_setfillcount(isc_mempool_t *mpctx,
c7f22f83aac9e61dafee191cad040e9c42652cc8David Lawrence unsigned int limit);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Sets the fillcount.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Additional requirements:
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff#endif /* MEM_H */