This documents that the way to choose a non-interrupt safe backend
allocator is by passing the PR_WAITOK flag to pool_init(). Also
documentes that this means that pool_put() may sleep[1] in that case,
something that mikeb@ noted yesterday.
ok?
[1] The non-interrupt safe multi page allocator (used for pools with
large items) uses the kernel_map and will sleep if it can't
immediately lock that map.
Index: pool.9
===================================================================
RCS file: /cvs/src/share/man/man9/pool.9,v
retrieving revision 1.49
diff -u -p -r1.49 pool.9
--- pool.9 2 Jul 2014 05:48:38 -0000 1.49
+++ pool.9 5 Sep 2015 11:29:11 -0000
@@ -129,10 +129,12 @@ The back-end allocator used to manage th
.Fa palloc
may be
.Dv NULL ,
-in which case the pool manager uses an interrupt safe allocator.
-It is recommended that this be set to
-.Em pool_allocator_nointr
-if the pool will never be accessed in an interrupt context.
+in which case the pool manager chooses an appropriate back-end allocator.
+If the
+.Dv PR_WAITOK
+flag has been specified, this allocator may not be interrupt safe.
+It is recommended to specify this flag if the pool will never be
+accessed in interrupt context.
.El
.Ss DESTROYING A POOL
The
@@ -193,8 +195,7 @@ If the number of available items in the
size set by
.Fn pool_sethiwat
and there are no outstanding requests for pool items,
-the excess items will be returned to the system by calling
-.Fn prelease .
+the excess items will be returned to the system if possible.
.Bl -tag -offset indent -width "item"
.It Fa pp
The handle identifying the pool resource instance.
@@ -202,6 +203,13 @@ The handle identifying the pool resource
A pointer to a pool item previously obtained by
.Fn pool_get .
.El
+.Pp
+If a non-interrupt safe allocator has been selected by passing the
+.Dv PR_WAITOK
+flag to
+.Fn pmap_init ,
+.Fn pool_put
+may sleep when completely unused pages are released.
.Ss PRIMING A POOL
.Fn pool_prime
adds items to the pool.
@@ -239,8 +247,7 @@ The handle identifying the pool resource
The maximum number of items to keep in the pool.
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
-.Pq by calling Fn prelease .
+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,
