[src/trunk]: src/share/man/man9 Document PR_PSERIALIZE. Remove documentation...

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

details:   https://anonhg.NetBSD.org/src/rev/e4e888ab3061
branches:  trunk
changeset: 1029134:e4e888ab3061
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Wed Dec 22 17:28:17 2021 +0000

description:
Document PR_PSERIALIZE.  Remove documentation for pool_cache_setpredestruct().

diffstat:

 distrib/sets/lists/comp/mi  |   8 ++++----
 share/man/man9/Makefile     |   5 ++---
 share/man/man9/pool.9       |  22 +++++++++++++++++++---
 share/man/man9/pool_cache.9 |  38 ++++++++++++++++++++------------------
 4 files changed, 45 insertions(+), 28 deletions(-)

diffs (172 lines):

diff -r beaa9a2f7ca8 -r e4e888ab3061 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Wed Dec 22 16:57:28 2021 +0000
+++ b/distrib/sets/lists/comp/mi        Wed Dec 22 17:28:17 2021 +0000
@@ -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
diff -r beaa9a2f7ca8 -r e4e888ab3061 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Wed Dec 22 16:57:28 2021 +0000
+++ b/share/man/man9/Makefile   Wed Dec 22 17:28:17 2021 +0000
@@ -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 @@
        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 \
diff -r beaa9a2f7ca8 -r e4e888ab3061 share/man/man9/pool.9
--- a/share/man/man9/pool.9     Wed Dec 22 16:57:28 2021 +0000
+++ b/share/man/man9/pool.9     Wed Dec 22 17:28:17 2021 +0000
@@ -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 @@
 .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
diff -r beaa9a2f7ca8 -r e4e888ab3061 share/man/man9/pool_cache.9
--- a/share/man/man9/pool_cache.9       Wed Dec 22 16:57:28 2021 +0000
+++ b/share/man/man9/pool_cache.9       Wed Dec 22 17:28:17 2021 +0000
@@ -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 @@
 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 @@
 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