mem.h revision f859f35d857ba99d0fff548db6d568499a58de63
7aacbd685b2107670e4179689abec9cb82d972abBob 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
ac70da9a2710aa9f343d2f720eb1bdd4191a79caBob Halleytypedef void (*isc_memfree_t)(void *, void *);
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * Define to 0 to remove the names from memory pools. This will save
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graff * about 16 bytes per pool.
4cafb28abcaa2a485c7aac1696213435538b92edBob Halley#define isc_mem_get(c, s) __isc_mem_getdebug(c, s, __FILE__, __LINE__)
4cafb28abcaa2a485c7aac1696213435538b92edBob Halley#define isc_mem_put(c, p, s) __isc_mem_putdebug(c, p, s, __FILE__, __LINE__)
eb7ef395d27b1104f684e21836f200c052736d07Michael Graff#define isc_mempool_get(c) __isc_mempool_getdebug(c, __FILE__, __LINE__)
b0cab8639f067aa2d35966a43d37aa5c88fbb415Bob Halley#define isc_mempool_put(c, p) __isc_mempool_putdebug(c, p, \
4cafb28abcaa2a485c7aac1696213435538b92edBob Halley#endif /* ISC_MEM_DEBUG */
4cafb28abcaa2a485c7aac1696213435538b92edBob Halleyisc_result_t isc_mem_create(size_t, size_t, isc_mem_t **);
f859f35d857ba99d0fff548db6d568499a58de63Mark Andrewsvoid __isc_mem_put(isc_mem_t *, void *, size_t);
de9282a1eaa50764fdc2e88046f8ff3522e3092eBob Halley const char *, int);
4cafb28abcaa2a485c7aac1696213435538b92edBob Halley size_t, const char *, int);
0ef59eaa9f7db0ebc00127e43f030f9adddd53efJames Bristerisc_boolean_t isc_mem_destroy_check(isc_mem_t *, isc_boolean_t);
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley#define memget(s) __memget_debug(s, __FILE__, __LINE__)
138d22b316c7cd10eaa9df2ee0e3ec712a077153Bob Halley#define memput(p, s) __memput_debug(p, s, __FILE__, __LINE__)
de9282a1eaa50764fdc2e88046f8ff3522e3092eBob Halley#endif /* ISC_MEMCLUSTER_LEGACY */
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.
eb7ef395d27b1104f684e21836f200c052736d07Michael Graffvoid __isc_mempool_put(isc_mempool_t *, void *);
eb7ef395d27b1104f684e21836f200c052736d07Michael Graffvoid * __isc_mempool_getdebug(isc_mempool_t *, const char *, int);
eb7ef395d27b1104f684e21836f200c052736d07Michael Graffvoid __isc_mempool_putdebug(isc_mempool_t *, void *,
eb7ef395d27b1104f684e21836f200c052736d07Michael Graff const char *, int);
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
78b2f25c9afee0d16f2e75882d9763abcb0872e5Michael Graffisc_mempool_setname(isc_mempool_t *mpctx, 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.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * For instance, setting "maxalloc" to a number larger 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 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);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns the maximum allowed number of allocations.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffvoid isc_mempool_setmaxalloc(isc_mempool_t *mpctx,
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff unsigned int limit);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Sets the maximum allowed number of allocations.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Additional requirements:
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffunsigned int isc_mempool_getallocated(isc_mempool_t *mpctx);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Returns the number of items allocated from this pool.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffunsigned 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.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graffvoid isc_mempool_setfillcount(isc_mempool_t *mpctx,
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff unsigned int limit);
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Sets the fillcount.
f28a94af2179ff7592d732e409d006582e9af7c3Michael Graff * Additional requirements:
4cafb28abcaa2a485c7aac1696213435538b92edBob Halley#endif /* MEM_H */