Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document pool_sethardlimit.

This commit is contained in:
jym 2011-11-14 02:38:05 +00:00
parent 81742ac3ab
commit f83fbb4ade
1 changed files with 30 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
share/man/man9/pool.9
View File

@ -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.