NAME
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,
pool_cache_sethardlimit —
resource-pool cache manager
SYNOPSIS
#include <sys/pool.h>
pool_cache_t
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 *),
void *arg);
void
pool_cache_destroy(
pool_cache_t
pc);
void *
pool_cache_get_paddr(
pool_cache_t
pc,
int flags,
paddr_t *pap);
void *
pool_cache_get(
pool_cache_t
pc,
int flags);
void
pool_cache_put_paddr(
pool_cache_t
pc,
void *object,
paddr_t pa);
void
pool_cache_put(
pool_cache_t
pc,
void *object);
void
pool_cache_destruct_object(
pool_cache_t
pc,
void *object);
void
pool_cache_invalidate(
pool_cache_t
pc);
void
pool_cache_sethiwat(
pool_cache_t
pc,
int nitems);
void
pool_cache_setlowat(
pool_cache_t
pc,
int nitems);
void
pool_cache_sethardlimit(
pool_cache_t
pc,
int nitems,
const char *warnmess,
int ratecap);
DESCRIPTION
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 continue operation
independent of the memory resources currently available from the system-wide
memory allocator.
pool_cache follows the
pool(9) API closely and offers
routines that are functionally equivalent to their
pool(9) counterparts. In addition,
pool_cache provides object management functions used to
manipulate objects allocated from the pool. It also maintains global and
per-CPU caches, both levels of cache work together to allow for low overhead
allocation and release of objects, and improved L1/L2/L3 hardware cache
locality in multiprocessor systems.
FUNCTIONS
-
-
- pool_cache_init(size,
align, align_offset,
flags, name,
palloc, ipl,
ctor, dtor,
arg)
-
Allocate and initialize a pool cache. The arguments are:
-
-
- size
-
Specifies the size of the memory items managed by the pool.
-
-
- align
-
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.
-
-
- align_offset
-
The offset within an item to which the align
parameter applies.
-
-
- flags
-
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.
-
-
- name
-
The name used to identify the object in diagnostic output.
-
-
- palloc
-
Should be typically be set to NULL, instructing
pool_cache_init() to select an appropriate back-end
allocator. 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.
-
-
- ipl
-
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 additional synchronization for access to it.
-
-
- ctor
-
Specifies a constructor used to initialize newly allocated objects. If
no constructor is required, specify
NULL
. The
first argument to ctor is
arg, the second is the new object, and the third
is flags.
-
-
- dtor
-
Specifies a destructor used to destroy cached objects prior to their
release to backing store. If no destructor is required, specify
NULL
. The first argument to
dtor is arg, and the
second is the object.
-
-
- arg
-
This value of this argument will be passed to both the constructor and
destructor routines.
-
-
- pool_cache_destroy(pc)
-
Destroy a pool cache pc. All other access to the cache
must be stopped before this call can be made.
-
-
- pool_cache_get_paddr(pc,
flags, pap)
-
Get an object from a pool cache pc. If
pap is not
NULL
, physical
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(pc,
flags)
-
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(pc,
object)
-
pool_cache_put() is the same as
pool_cache_put_paddr() with
POOL_PADDR_INVALID
pa
argument. It's implemented as a macro.
-
-
- pool_cache_destruct_object(pc,
object)
-
Force destruction of an object object and release it
back into the pool.
-
-
- pool_cache_invalidate(pc)
-
Invalidate a pool cache pc. All objects in the cache
will be destructed and freed back to the pool backing the cache. For pool
caches that vend constructed objects, consumers of this API must take care
to provide proper synchronization between the input to the constructor and
cache invalidation.
-
-
- pool_cache_sethiwat(pc,
nitems)
-
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 limits 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 function 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 unused pages.
-
-
- pool_cache_setlowat(pc,
nitems)
-
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 function.
-
-
- pool_cache_sethardlimit(pc,
nitems, warnmess,
ratecap)
- Set the hard limit for the backing
pool(9) to
nitems. When the hard limit is reached, the warning
message warnmess will be logged.
ratecap represents the minimal interval (in seconds)
after which another warning message is issued when the pool hits its hard
limit again.
CODE REFERENCES
The
pool_cache subsystem is implemented within the file
sys/kern/subr_pool.c.
SEE ALSO
intro(9),
kmem(9),
memoryallocators(9),
percpu(9),
pool(9)