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