Module Name: src
Committed By: jym
Date: Mon Nov 14 02:38:06 UTC 2011
Modified Files:
src/share/man/man9: pool.9
Log Message:
Document pool_sethardlimit.
To generate a diff of this commit:
cvs rdiff -u -r1.43 -r1.44 src/share/man/man9/pool.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/pool.9
diff -u src/share/man/man9/pool.9:1.43 src/share/man/man9/pool.9:1.44
--- src/share/man/man9/pool.9:1.43 Wed Apr 30 13:10:58 2008
+++ src/share/man/man9/pool.9 Mon Nov 14 02:38:05 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: pool.9,v 1.43 2008/04/30 13:10:58 martin Exp $
+.\" $NetBSD: pool.9,v 1.44 2011/11/14 02:38:05 jym Exp $
.\"
.\" Copyright (c) 1997, 1998, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd July 25, 2007
+.Dd November 14, 2011
.Dt POOL 9
.Os
.Sh NAME
@@ -37,7 +37,8 @@
.Nm pool_put ,
.Nm pool_prime ,
.Nm pool_sethiwat ,
-.Nm pool_setlowat
+.Nm pool_setlowat ,
+.Nm pool_sethardlimit
.Nd resource-pool manager
.Sh SYNOPSIS
.In sys/pool.h
@@ -64,6 +65,9 @@
.Fn pool_sethiwat "struct pool *pp" "int n"
.Ft void
.Fn pool_setlowat "struct pool *pp" "int n"
+.Ft void
+.Fn pool_sethardlimit "struct pool *pp" "int n" \
+"const char *warnmess" "int ratecap"
.Sh DESCRIPTION
These utility routines provide management of pools of fixed-sized
areas of memory.
@@ -218,12 +222,13 @@ This function may return
in case the requested number of items could not be allocated.
Otherwise,
the return value is 0.
-.Ss SETTING POOL RESOURCE WATERMARKS
+.Ss SETTING POOL RESOURCE WATERMARKS AND LIMITS
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.
+.Pp
The limits for the minimum and maximum number of items which a pool should keep
at hand are known as the high and low
.Sy watermarks .
@@ -233,6 +238,13 @@ and
.Fn pool_setlowat
set a pool's high and low watermarks, respectively.
.Pp
+The hard limit represents the maximum number of items a pool is allowed
+to allocate at any given time.
+Unless modified via
+.Fn pool_sethardlimit ,
+the hard limit defaults to
+.Dv UINT_MAX .
+.Pp
.Fn pool_sethiwat
.Bl -tag -offset indent -width "flags"
.It Fa pp
@@ -260,6 +272,20 @@ Unlike
.Fn pool_prime ,
this function does not allocate the necessary memory up-front.
.El
+.Pp
+.Fn pool_sethardlimit
+.Bl -tag -offset indent -width "flags"
+.It Fa pp
+The handle identifying the pool resource instance.
+.It Fa n
+The maximum number of items to be allocated from the pool (i.e. the
+hard limit).
+.It Fa warnmess
+The warning message that will be logged when the hard limit is reached.
+.It Fa ratecap
+The minimal interval (in seconds) after which another warning message
+is issued when the pool hits its hard limit again.
+.El
.Ss POTENTIAL PITFALLS
Note that undefined behaviour results when mixing the storage providing
methods supported by the pool resource routines.
