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);
void
pool_prime
(struct
pool *pp, int
n);
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
, or
PR_PSERIALIZE
. 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. If PR_PSERIALIZE
is given, then the
allocator guarantees that a passive serialization barrier equivalent to
“xc_barrier(0)” will be performed before the object's
backing store is returned to the system.
PR_PSERIALIZE
implies
PR_NOTOUCH
. Because of the guarantees provided by
PR_PSERIALIZE
, objects muste never be freed to a
pool using this option from either hard or soft interrupt context, as
doing so may block.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
().The targets for the minimum and maximum number of free items which
a pool should try to keep available 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 limits for the minimum and maximum number of total items (both
free and allocated) that the pool can have at any time are specified by the
functions pool_prime
() and
pool_sethardlimit
(), respectively. The defaults for
these limits are 0
and
UINT_MAX
, respectively. Changing these limits will
cause memory to be immediately allocated to the pool or freed from the pool
as needed.
pool_sethiwat
()
pool_setlowat
()
pool_sethardlimit
()
pool_prime
()
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
.
April 12, 2020 | NetBSD 10.1 |