Module Name: src
Committed By: thorpej
Date: Wed Dec 22 17:28:18 UTC 2021
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile pool.9 pool_cache.9
Log Message:
Document PR_PSERIALIZE. Remove documentation for pool_cache_setpredestruct().
To generate a diff of this commit:
cvs rdiff -u -r1.2400 -r1.2401 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.459 -r1.460 src/share/man/man9/Makefile
cvs rdiff -u -r1.49 -r1.50 src/share/man/man9/pool.9
cvs rdiff -u -r1.23 -r1.24 src/share/man/man9/pool_cache.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2400 src/distrib/sets/lists/comp/mi:1.2401
--- src/distrib/sets/lists/comp/mi:1.2400 Tue Dec 21 18:59:22 2021
+++ src/distrib/sets/lists/comp/mi Wed Dec 22 17:28:17 2021
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2400 2021/12/21 18:59:22 thorpej Exp $
+# $NetBSD: mi,v 1.2401 2021/12/22 17:28:17 thorpej Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -12282,7 +12282,7 @@
./usr/share/man/cat9/pool_cache_sethardlimit.0 comp-sys-catman .cat
./usr/share/man/cat9/pool_cache_sethiwat.0 comp-sys-catman .cat
./usr/share/man/cat9/pool_cache_setlowat.0 comp-sys-catman .cat
-./usr/share/man/cat9/pool_cache_setpredestruct.0 comp-sys-catman .cat
+./usr/share/man/cat9/pool_cache_setpredestruct.0 comp-obsolete obsolete
./usr/share/man/cat9/pool_create.0 comp-sys-catman .cat
./usr/share/man/cat9/pool_destroy.0 comp-sys-catman .cat
./usr/share/man/cat9/pool_get.0 comp-sys-catman .cat
@@ -20475,7 +20475,7 @@
./usr/share/man/html9/pool_cache_sethardlimit.html comp-sys-htmlman html
./usr/share/man/html9/pool_cache_sethiwat.html comp-sys-htmlman html
./usr/share/man/html9/pool_cache_setlowat.html comp-sys-htmlman html
-./usr/share/man/html9/pool_cache_setpredestruct.html comp-sys-htmlman html
+./usr/share/man/html9/pool_cache_setpredestruct.html comp-obsolete obsolete
./usr/share/man/html9/pool_create.html comp-sys-htmlman html
./usr/share/man/html9/pool_destroy.html comp-sys-htmlman html
./usr/share/man/html9/pool_get.html comp-sys-htmlman html
@@ -28829,7 +28829,7 @@
./usr/share/man/man9/pool_cache_sethardlimit.9 comp-sys-man .man
./usr/share/man/man9/pool_cache_sethiwat.9 comp-sys-man .man
./usr/share/man/man9/pool_cache_setlowat.9 comp-sys-man .man
-./usr/share/man/man9/pool_cache_setpredestruct.9 comp-sys-man .man
+./usr/share/man/man9/pool_cache_setpredestruct.9 comp-obsolete obsolete
./usr/share/man/man9/pool_create.9 comp-sys-man .man
./usr/share/man/man9/pool_destroy.9 comp-sys-man .man
./usr/share/man/man9/pool_get.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.459 src/share/man/man9/Makefile:1.460
--- src/share/man/man9/Makefile:1.459 Tue Dec 21 18:59:22 2021
+++ src/share/man/man9/Makefile Wed Dec 22 17:28:17 2021
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.459 2021/12/21 18:59:22 thorpej Exp $
+# $NetBSD: Makefile,v 1.460 2021/12/22 17:28:17 thorpej Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -758,8 +758,7 @@ MLINKS+=pool_cache.9 pool_cache_init.9 \
pool_cache.9 pool_cache_invalidate.9 \
pool_cache.9 pool_cache_sethiwat.9 \
pool_cache.9 pool_cache_setlowat.9 \
- pool_cache.9 pool_cache_sethardlimit.9 \
- pool_cache.9 pool_cache_setpredestruct.9
+ pool_cache.9 pool_cache_sethardlimit.9
MLINKS+=powerhook_establish.9 powerhook_disestablish.9
MLINKS+=preempt.9 yield.9
MLINKS+=pserialize.9 pserialize_create.9 \
Index: src/share/man/man9/pool.9
diff -u src/share/man/man9/pool.9:1.49 src/share/man/man9/pool.9:1.50
--- src/share/man/man9/pool.9:1.49 Mon Apr 13 08:59:14 2020
+++ src/share/man/man9/pool.9 Wed Dec 22 17:28:17 2021
@@ -1,4 +1,4 @@
-.\" $NetBSD: pool.9,v 1.49 2020/04/13 08:59:14 wiz Exp $
+.\" $NetBSD: pool.9,v 1.50 2021/12/22 17:28:17 thorpej Exp $
.\"
.\" Copyright (c) 1997, 1998, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -98,12 +98,28 @@ The offset within an item to which the
.Fa align
parameter applies.
.It Fa flags
-Should be set to zero or
-.Dv PR_NOTOUCH .
+Should be set to zero,
+.Dv PR_NOTOUCH ,
+or
+.Dv PR_PSERIALIZE .
If
.Dv 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
+.Dv PR_PSERIALIZE
+is given, then the allocator guarantees that a passive serialization
+barrier equivalent to
+.Dq xc_barrier(0)
+will be performed before the object's backing store is returned to
+the system.
+.Dv PR_PSERIALIZE
+implies
+.Dv PR_NOTOUCH .
+Because of the guarantees provided by
+.Dv 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.
.It Fa wchan
The
.Sq wait channel
Index: src/share/man/man9/pool_cache.9
diff -u src/share/man/man9/pool_cache.9:1.23 src/share/man/man9/pool_cache.9:1.24
--- src/share/man/man9/pool_cache.9:1.23 Tue Dec 21 18:59:22 2021
+++ src/share/man/man9/pool_cache.9 Wed Dec 22 17:28:17 2021
@@ -1,4 +1,4 @@
-.\" $NetBSD: pool_cache.9,v 1.23 2021/12/21 18:59:22 thorpej Exp $
+.\" $NetBSD: pool_cache.9,v 1.24 2021/12/22 17:28:17 thorpej Exp $
.\"
.\" Copyright (c)2003 YAMAMOTO Takashi,
.\" All rights reserved.
@@ -69,8 +69,7 @@
.Nm pool_cache_invalidate ,
.Nm pool_cache_sethiwat ,
.Nm pool_cache_setlowat ,
-.Nm pool_cache_sethardlimit ,
-.Nm pool_cache_setpredestruct
+.Nm pool_cache_sethardlimit
.Nd resource-pool cache manager
.\" ------------------------------------------------------------
.Sh SYNOPSIS
@@ -120,10 +119,6 @@
.Fn pool_cache_sethardlimit \
"pool_cache_t pc" "int n" "const char *warnmess" "int ratecap"
.\" ------------------------------------------------------------
-.Ft void
-.Fn pool_cache_setpredestruct \
-"pool_cache_t pc" "void (*fn)(void *)"
-.\" ------------------------------------------------------------
.Sh DESCRIPTION
These utility routines provide management of pools of fixed-sized
areas of memory.
@@ -175,12 +170,28 @@ The offset within an item to which the
parameter applies.
.It Fa flags
.Pp
-Should be set to zero or
-.Dv PR_NOTOUCH .
+Should be set to zero,
+.Dv PR_NOTOUCH ,
+or
+.Dv PR_PSERIALIZE .
If
.Dv 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
+.Dv PR_PSERIALIZE
+is given, then the allocator guarantees that a passive serialization barrier
+equivalent to
+.Dq xc_barrier(0)
+will be performed before either the object's destructor is called or
+before object's backing store is returned to the system.
+.Dv PR_PSERIALIZE
+implies
+.Dv PR_NOTOUCH .
+Because of the guarantees provided by
+.Dv PR_PSERIALIZE ,
+objects must never be freed to a pool cache using this option
+from either hard or soft interrupt context, as doing so may block.
.It Fa name
.Pp
The name used to identify the object in diagnostic output.
@@ -352,15 +363,6 @@ will be logged.
represents the minimal interval (in seconds) after which another warning
message is issued when the pool hits its hard limit again.
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-.It Fn pool_cache_setpredestruct "fn"
-Sets a pre-destructor hook for the pool cache.
-This hook will be invoked
-.Pq with the same argument passed to the destructor
-before a batch of one or more objects is destructed.
-Pool cache users who rely on type-stability or use other
-forms of passive serialization may use this hook as a
-synchronization point.
-.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
.It Fn pool_cache_prime "pc" "n"
Set the minimum number of total items (both free and allocated) for the backing
.Xr pool 9
