[src/trunk]: src/share/man/man9 Document pool_sethardlimit.

[jym <jym%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/ee8dc56ef5a1
branches:  trunk
changeset: 771205:ee8dc56ef5a1
user:      jym <jym%NetBSD.org@localhost>
date:      Mon Nov 14 02:38:05 2011 +0000

description:
Document pool_sethardlimit.

diffstat:

 share/man/man9/pool.9 |  34 ++++++++++++++++++++++++++++++----
 1 files changed, 30 insertions(+), 4 deletions(-)

diffs (88 lines):

diff -r 9d8516ed49c8 -r ee8dc56ef5a1 share/man/man9/pool.9
--- a/share/man/man9/pool.9     Mon Nov 14 01:27:42 2011 +0000
+++ b/share/man/man9/pool.9     Mon Nov 14 02:38:05 2011 +0000
@@ -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 @@
 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 @@
 .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 @@
 .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.