POOL(9) | Kernel Developer's Manual | POOL(9) |
pool_init
, pool_destroy
,
pool_get
, pool_put
,
pool_prime
, pool_sethiwat
,
pool_setlowat
,
pool_sethardlimit
—
#include <sys/pool.h>
void
pool_init
(struct pool *pp,
size_t size, u_int align,
u_int align_offset, int flags,
const char *wchan, struct
pool_allocator *palloc, int ipl);
void
pool_destroy
(struct
pool *pp);
void *
pool_get
(struct
pool *pp, int
flags);
void
pool_put
(struct
pool *pp, void
*item);
int
pool_prime
(struct
pool *pp, int
nitems);
void
pool_sethiwat
(struct
pool *pp, int
n);
void
pool_setlowat
(struct
pool *pp, int
n);
void
pool_sethardlimit
(struct
pool *pp, int n,
const char *warnmess,
int ratecap);
pool_init
() initializes a resource pool.
The arguments are:
pool_get
(). This argument must be a power of two.
If zero, the alignment defaults to an architecture-specific natural
alignment.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.pool_get
() must wait for items to be returned to
the pool.NULL
or
pool_allocator_kmem
, in which case the default
kernel memory allocator will be used. It can also be set to
pool_allocator_nointr
when the pool will never be
accessed from interrupt context.pool_destroy
() destroys a resource pool. It
takes a single argument pp identifying the pool resource
instance.
pool_get
() allocates an item from the pool and returns a
pointer to it. The arguments are:
PR_NOWAIT
is given,
pool_get
() returns NULL
.
If PR_WAITOK
is given and allocation is attempted
with no resources available, the function will sleep until items are
returned to the pool. If both PR_LIMITFAIL
and
PR_WAITOK
are specified, and the pool has reached
its hard limit, pool_get
() will return
NULL
without waiting, allowing the caller to do
its own garbage collection; however, it will still wait if the pool is not
yet at its hard limit. If the PR_ZERO
flag is
specified, then the memory returned will be zeroed first using
memset(3).pool_put
() returns the pool item pointed at by
item to the resource pool identified by the pool handle
pp. If the number of available items in the pool exceeds
the maximum pool size set by pool_sethiwat
() and there
are no outstanding requests for pool items, the excess items will be returned
to the system. The arguments to pool_put
() are:
pool_get
().pool_prime
() adds items to the pool. Storage space for
the items is allocated by using the page allocation routine specified to
pool_create
().
The arguments to pool_prime
() are:
This function may return ENOMEM
in case
the requested number of items could not be allocated. Otherwise, the return
value is 0.
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 functions
pool_sethiwat
() and
pool_setlowat
() set a pool's high and low
watermarks, respectively.
The hard limit represents the maximum number of items a pool is
allowed to allocate at any given time. Unless modified via
pool_sethardlimit
(), the hard limit defaults to
UINT_MAX
.
pool_sethiwat
()
pool_setlowat
()
pool_prime
(), this function does not allocate the
necessary memory up-front.pool_sethardlimit
()
The pool resource code uses a per-pool lock to protect its
internal state. If any pool functions are called in an interrupt context,
the caller must block all interrupts that might cause the code to be
reentered. Additionally, the functions pool_init
()
and pool_destroy
() should never be called in
interrupt context.
POOL_DIAGNOSTIC
.
February 10, 2019 | NetBSD 9.2 |