[src/trunk]: src/share/man/man9 a pool_cache(9) manpage.

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/share/man/man9 a pool_cache(9) manpage.
From: yamt <yamt%NetBSD.org@localhost>
Date: Fri, 24 Jan 2020 13:36:53 +0000
details:   https://anonhg.NetBSD.org/src/rev/88bcc7b48678
branches:  trunk
changeset: 551494:88bcc7b48678
user:      yamt <yamt%NetBSD.org@localhost>
date:      Sun Sep 07 11:24:34 2003 +0000

description:
a pool_cache(9) manpage.
maybe incomplete, but better than none.

diffstat:

 share/man/man9/Makefile     |   15 ++-
 share/man/man9/pool_cache.9 |  232 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 244 insertions(+), 3 deletions(-)

diffs (272 lines):

diff -r de4e748222a0 -r 88bcc7b48678 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Sun Sep 07 11:16:59 2003 +0000
+++ b/share/man/man9/Makefile   Sun Sep 07 11:24:34 2003 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.143 2003/09/06 18:12:39 yamt Exp $
+#       $NetBSD: Makefile,v 1.144 2003/09/07 11:24:34 yamt Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -23,8 +23,8 @@
        microtime.9 mstohz.9 namecache.9 namei.9 need_resched.9 \
        panic.9 pci.9 pci_configure_bus.9 pci_intr.9 \
        pcmcia.9 pfil.9 physio.9 \
-       pmap.9 pmc.9 pool.9 powerhook_establish.9 ppsratecheck.9 properties.9 \
-       preempt.9 \
+       pmap.9 pmc.9 pool.9 pool_cache.9 powerhook_establish.9 ppsratecheck.9 \
+       properties.9 preempt.9 \
        radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rt_timer.9 \
        SCHED_LOCK.9 scheduler.9 \
        scsipi.9 setjmp.9 setrunqueue.9 shutdownhook_establish.9 \
@@ -355,6 +355,15 @@
 MLINKS+=pool.9 pool_create.9 pool.9 pool_destroy.9 pool.9 pool_get.9 \
        pool.9 pool_init.9 pool.9 pool_put.9 pool.9 pool_prime.9 \
        pool.9 pool_sethiwat.9 pool.9 pool_setlowat.9
+MLINKS+=pool_cache.9 pool_cache.9 \
+       pool_cache.9 pool_cache_init.9 \
+       pool_cache.9 pool_cache_destroy.9 \
+       pool_cache.9 pool_cache_get_paddr.9 \
+       pool_cache.9 pool_cache_get.9 \
+       pool_cache.9 pool_cache_put_paddr.9 \
+       pool_cache.9 pool_cache_put.9 \
+       pool_cache.9 pool_cache_destruct_object.9 \
+       pool_cache.9 pool_cache_invalidate.9
 MLINKS+=powerhook_establish.9 powerhook_disestablish.9
 MLINKS+=properties.9 propdb_create.9 \
        properties.9 propdb_destroy.9 \
diff -r de4e748222a0 -r 88bcc7b48678 share/man/man9/pool_cache.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/pool_cache.9       Sun Sep 07 11:24:34 2003 +0000
@@ -0,0 +1,232 @@
+.\"    $NetBSD: pool_cache.9,v 1.1 2003/09/07 11:24:35 yamt Exp $
+.\"
+.\" Copyright (c)2003 YAMAMOTO Takashi,
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"
+.\" following copyright notice is from sys/kern/subr_pool.c.
+.\" they are here because i took some comments from it.  yamt%netbsd.org@localhost
+.\"
+.\"
+.\"/*-
+.\" * Copyright (c) 1997, 1999, 2000 The NetBSD Foundation, Inc.
+.\" * All rights reserved.
+.\" *
+.\" * This code is derived from software contributed to The NetBSD Foundation
+.\" * by Paul Kranenburg; by Jason R. Thorpe of the Numerical Aerospace
+.\" * Simulation Facility, NASA Ames Research Center.
+.\" *
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions
+.\" * are met:
+.\" * 1. Redistributions of source code must retain the above copyright
+.\" *    notice, this list of conditions and the following disclaimer.
+.\" * 2. Redistributions in binary form must reproduce the above copyright
+.\" *    notice, this list of conditions and the following disclaimer in the
+.\" *    documentation and/or other materials provided with the distribution.
+.\" * 3. All advertising materials mentioning features or use of this software
+.\" *    must display the following acknowledgement:
+.\" *  This product includes software developed by the NetBSD
+.\" *  Foundation, Inc. and its contributors.
+.\" * 4. Neither the name of The NetBSD Foundation nor the names of its
+.\" *    contributors may be used to endorse or promote products derived
+.\" *    from this software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" * POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.\"
+.\" ------------------------------------------------------------
+.Dd September 8, 2003
+.Dt POOL_CACHE 9
+.Os
+.\" ------------------------------------------------------------
+.Sh NAME
+.Nm pool_cache ,
+.Nm pool_cache_init ,
+.Nm pool_cache_destroy ,
+.Nm pool_cache_get_paddr ,
+.Nm pool_cache_get ,
+.Nm pool_cache_put_paddr ,
+.Nm pool_cache_put ,
+.Nm pool_cache_destruct_object ,
+.Nm pool_cache_invalidate
+.Nd resource-pool cache manager
+.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.In sys/pool.h
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn pool_cache_init \
+"struct pool_cache *pc" "struct pool *pp" \
+"int (*ctor)(void *, void *, int)" "void (*dtor)(void *, void *)" "void *arg"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn pool_cache_destroy \
+"struct pool_cache *pc"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void *
+.Fn pool_cache_get_paddr \
+"struct pool_cache *pc" "int flags" "paddr_t *pap"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void *
+.Fn pool_cache_get \
+"struct pool_cache *pc" "int flags"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn pool_cache_put_paddr \
+"struct pool_cache *pc" "void *object" "paddr_t pa"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn pool_cache_put \
+"struct pool_cache *pc" "void *object"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn pool_cache_destruct_object \
+"struct pool_cache *pc" "void *object"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn pool_cache_invalidate \
+"struct pool_cache *pc"
+.\" ------------------------------------------------------------
+.Sh DESCRIPTION
+The
+.Nm
+utility routines are provided to support caching of constructed objects,
+similar to the Solaris SLAB allocator.
+.Nm
+uses
+.Xr pool 9
+to allocate memory areas used for objects.
+If the pool must be protected from interrupts,
+.Nm
+routines expect to be called at the appropriate interrupt priority level.
+.\" ------------------------------------------------------------
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn pool_cache_init "pc" "pp" "ctor" "dtor" "arg"
+Initialize a pool cache
+.Fa pc .
+The pool
+.Fa pp
+should be initialized byt the caller in advance.
+.Fa ctor
+and
+.Fa dtor
+are object constructor and destructor.
+They can be
+.Dv NULL .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn pool_cache_destroy "pc"
+Destroy a pool cache
+.Fa pc .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn pool_cache_get_paddr "pc" "flags" "pap"
+Get an object from a pool cache
+.Fa pc .
+If
+.Fa pap
+is not
+.Dv NULL ,
+physical address of the object or
+.Dv POOL_PADDR_INVALID
+will be returned via it.
+.Fa flags
+will be passed to
+.Fn pool_get
+function of the backing
+.Xr pool
+and the object constructor specified when the pool cache is created by
+.Fn pool_cache_init .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn pool_cache_get "pc" "flags"
+.Fn pool_cache_get
+is the same as
+.Fn pool_cache_get_paddr
+with
+.Dv NULL
+.Fa pap
+argument.
+It's implemented as a macro.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn pool_cache_put_paddr "pc" "object" "pa"
+Put an object
+.Fa object
+back to the pool cache
+.Fa pc .
+.Fa pa
+should be physical address of the object
+.Fa object
+or
+.Dv POOL_PADDR_INVALID .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn pool_cache_put "pc" "object"
+.Fn pool_cache_put
+is the same as
+.Fn pool_cache_put_paddr
+with
+.Dv POOL_PADDR_INVALID
+.Fa pa
+argument.
+It's implemented as a macro.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn pool_cache_destruct_object "pc" "object"
+Force destruction of an object
+.Fa object
+and its release back into the pool.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn pool_cache_invalidate "pc"
+Invalidate a pool cache
+.Fa pc .
+Destruct and release all of the cached objects.
+.El
+.\" ------------------------------------------------------------
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing the
+.Nm
+subsystem
+can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The
+.Nm
+subsystem is implemented within the file
+.Pa sys/kern/subr_pool.c .
+.Sh SEE ALSO
+.Xr intro 9 ,
+.Xr pool 9 ,
+.Xr malloc 9
Prev by Date: [src/trunk]: src/sys/kern Correctly check Mach-O fat header so that fat binar...
Next by Date: [src/trunk]: src/sys/dev/ic Codec id ADS 0x70 is AD1980, not AD1981.
Previous by Thread: [src/trunk]: src/sys/kern Correctly check Mach-O fat header so that fat binar...
Next by Thread: [src/trunk]: src/sys/dev/ic Codec id ADS 0x70 is AD1980, not AD1981.
Indexes:
Home | Main Index | Thread Index | Old Index