- NetBSD Manual Pages
POOL_CACHE(9) NetBSD Kernel Developer's Manual POOL_CACHE(9)
Powered by man-cgi (2021-06-01).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.
pool_cache, pool_cache_init, pool_cache_destroy, pool_cache_get_paddr,
pool_cache_get, pool_cache_put_paddr, pool_cache_put,
pool_cache_destruct_object, pool_cache_invalidate, pool_cache_sethiwat,
pool_cache_setlowat -- resource-pool cache manager
pool_cache_init(size_t size, u_int align, u_int align_offset, int flags,
const char *name, struct pool_allocator *palloc, int ipl,
int (*ctor)(void *, void *, int), void (*dtor)(void *, void *),
pool_cache_get_paddr(pool_cache_t pc, int flags, paddr_t *pap);
pool_cache_get(pool_cache_t pc, int flags);
pool_cache_put_paddr(pool_cache_t pc, void *object, paddr_t pa);
pool_cache_put(pool_cache_t pc, void *object);
pool_cache_destruct_object(pool_cache_t pc, void *object);
pool_cache_sethiwat(pool_cache_t pc, int nitems);
pool_cache_setlowat(pool_cache_t pc, int nitems);
These utility routines provide management of pools of fixed-sized areas
of memory. Resource pools set aside an amount of memory for exclusive
use by the resource pool owner. This can be used by applications to
guarantee the availability of a minimum amount of memory needed to con-
tinue operation independent of the memory resources currently available
from the system-wide memory allocator.
Global and per-CPU caches of constructed objects are maintained. The two
levels of cache work together to allow for low overhead allocation and
release of objects, and improved L1/L2/L3 hardware cache locality in mul-
pool_cache_init(pc, pp, ctor, dtor, arg)
Allocate and initialize a pool cache. The arguments are:
Specifies the size of the memory items managed by the
Specifies the memory address alignment of the items
returned by pool_cache_get(). This argument must be a
power of two. If zero, the alignment defaults to an
architecture-specific natural alignment.
The offset within an item to which the align parameter
Should be set to zero or PR_NOTOUCH. If PR_NOTOUCH is
given, free items are never used to keep internal state so
that the pool can be used for non memory backed objects.
The name used to identify the object in diagnostic output.
Should be typically be set to NULL, instructing
pool_cache_init() to select an appropriate back-end allo-
cator. Alternate allocators can be used to partition
space from arbitrary sources. Use of alternate allocators
is not documented here as it is not a stable, endorsed
part of the API.
Specifies an interrupt priority level that will block all
interrupt handlers that could potentially access the pool.
The pool_cache facility provides its own synchronization.
The users of any given pool_cache need not provide addi-
tional synchronization for access to it.
Specifies a constructor used to initialize newly allocated
objects. If no constructor is required, specify NULL.
Specifies a destructor used to destroy cached objects
prior to their release to backing store. If no destructor
is required, specify NULL.
This value of this argument will be passed to both the
constructor and destructor routines.
Destroy a pool cache. All other access to the cache must be
stopped before this call can be made. pc.
pool_cache_get_paddr(pc, flags, pap)
Get an object from a pool cache pc. If pap is not NULL, physi-
cal address of the object or POOL_PADDR_INVALID will be returned
via it. flags will be passed to pool_get() function of the
backing pool(9) and the object constructor specified when the
pool cache is created by pool_cache_init().
pool_cache_get() is the same as pool_cache_get_paddr() with NULL
pap argument. It's implemented as a macro.
pool_cache_put_paddr(pc, object, pa)
Put an object object back to the pool cache pc. pa should be
physical address of the object object or POOL_PADDR_INVALID.
pp. If the number of available items in the backing pool
exceeds the maximum pool size set by pool_cache_sethiwat() and
there are no outstanding requests for pool items, the excess
items will be returned to the system.
pool_cache_put() is the same as pool_cache_put_paddr() with
POOL_PADDR_INVALID pa argument. It's implemented as a macro.
Force destruction of an object object and its release back into
Invalidate a pool cache pc. Destruct and release all objects in
the global cache. Per-CPU caches will not be invalidated by
this call, meaning that it is still possible to allocate "stale"
items from the cache. If relevant, the user must check for this
condition when allocating items.
A pool will attempt to increase its resource usage to keep up
with the demand for its items. Conversely, it will return
unused memory to the system should the number of accumulated
unused items in the pool exceed a programmable limit. The lim-
its for the minimum and maximum number of items which a pool
should keep at hand are known as the high and low watermarks.
The function pool_cache_sethiwat() sets the backing pool's high
water mark. As items are returned and the total number of pages
in the pool is larger than the maximum set by this function, any
completely unused pages are released immediately. If this func-
tion is not used to specify a maximum number of items, the pages
will remain associated with the pool until the system runs low
on memory, at which point the VM system will try to reclaim
Set the minimum number of items to keep in the pool. The number
pages in the pool will not decrease below the required value to
accommodate the minimum number of items specified by this func-
This section describes places within the NetBSD source tree where actual
code implementing the pool_cache subsystem can be found. All pathnames
are relative to /usr/src.
The pool_cache subsystem is implemented within the file
intro(9), kmem_alloc(9), kmem_free(9), memoryallocators(9), pool(9)
NetBSD 5.0 Febuary 1, 2008 NetBSD 5.0