diff options
Diffstat (limited to 'static/netbsd/man9/pserialize.9')
| -rw-r--r-- | static/netbsd/man9/pserialize.9 | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/static/netbsd/man9/pserialize.9 b/static/netbsd/man9/pserialize.9 new file mode 100644 index 00000000..b87d746e --- /dev/null +++ b/static/netbsd/man9/pserialize.9 @@ -0,0 +1,188 @@ +.\" $NetBSD: pserialize.9,v 1.15 2025/10/01 12:33:10 riastradh Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" 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 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 January 26, 2016 +.Dt PSERIALIZE 9 +.Os +.Sh NAME +.Nm pserialize +.Nd passive serialization mechanism +.Sh SYNOPSIS +.In sys/pserialize.h +.Ft pserialize_t +.Fn pserialize_create "void" +.Ft void +.Fn pserialize_destroy "pserialize_t psz" +.Ft int +.Fn pserialize_read_enter "void" +.Ft void +.Fn pserialize_read_exit "int s" +.Ft void +.Fn pserialize_perform "pserialize_t psz" +.\" ----- +.Sh DESCRIPTION +Passive serialization is a reader / writer synchronisation mechanism +designed for lock-less read operations. +The read operations may happen from software interrupt at +.Dv IPL_SOFTCLOCK . +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pserialize_create +Allocate a new synchronisation object. +.It Fn pserialize_destroy +Destroy the synchronisation object. +No synchronisation activity should happen at this point. +.It Fn pserialize_read_enter +Enter the critical path of the reader side. +Returns an IPL value, which must be passed to +.Xr pserialize_read_exit 9 . +Protected code path is not allowed to block. +.It Fn pserialize_read_exit +Exit the critical path of the reader side. +Takes the IPL value returned by +.Xr pserialize_read_enter 9 . +.It Fn pserialize_perform +Perform the passive serialization on the writer side. +Passing of this function ensures that no readers are in action. +Writers are typically additionally serialized with a separate +mechanism, e.g. +.Xr mutex 9 , +to remove objects used by readers from a published list. +Operation blocks and it may only be performed from thread context. +.El +.\" ----- +.Sh EXAMPLES +Given a global database of frotz records: +.Bd -literal + struct frotz { + ... + struct frotz *f_next; + }; + + static struct { + kmutex_t lock; + pserialize_t psz; + struct frotz *first; + } frobbotzim __cacheline_aligned; +.Ed +.Pp +Create a frotz and publish it, as a writer: +.Bd -literal + struct frotz *f = pool_get(&frotz_pool, PR_WAITOK); + + /* Initialize f. */ + ... + + mutex_enter(&frobbotzim.lock); + f->f_next = frobbotzim.first; + /* + * Publish the contents of f->f_next before we publish the + * pointer to f in frobbotzim.first. + */ + atomic_store_release(&frobbotzim.first, f); + mutex_exit(&frobbotzim.lock); +.Ed +.Pp +Find a frotz, as a reader: +.Bd -literal + struct frotz *f; + int error = ENOENT; + int s; + + s = pserialize_read_enter(); + /* Fetch frobbotzim.first before we fetch anything it point to. */ + for (f = atomic_load_consume(&frobbotzim.first); + f != NULL; + f = f->f_next) { + if (f->f_... == key) { + /* + * Grab whatever part of the frotz we need. + * Note that we can't use the frotz after + * pserialize_read_exit, without a stronger + * kind of reference, say a reference count + * managed by atomic_ops(3). + */ + *resultp = f->f_...; + error = 0; + break; + } + } + pserialize_read_exit(s); + + return error; +.Ed +.Pp +Remove a frotz, as a writer, and free it once there are no more +readers: +.Bd -literal + struct frotz **fp, *f; + + mutex_enter(&frobbotzim.lock); + for (fp = &frobbotzim.first; (f = *fp) != NULL; fp = &f->f_next) { + if (f->f_... == key) { + /* + * Unhook it from the list. Readers may still + * be traversing the list at this point, so + * the next pointer must remain valid and + * memory must remain allocated. + */ + *fp = f->f_next; + break; + } + } + mutex_exit(&frobbotzim.lock); + + /* + * Wait for all existing readers to complete. New readers will + * not see f because the list no longer points to it. + */ + pserialize_perform(frobbotzim.psz); + + /* Now nobody else can be touching f, so it is safe to free. */ + if (f != NULL) + pool_put(&frotz_pool, f); +.Ed +.\" ----- +.Sh CODE REFERENCES +The +.Nm +is implemented within the file +.Pa sys/kern/subr_pserialize.c . +.Sh SEE ALSO +.Xr membar_ops 3 , +.Xr condvar 9 , +.Xr mutex 9 , +.Xr rwlock 9 +.Rs +.%A Hennessy, et al. +.%T "Passive serialization in a multitasking environment" +.%I US Patent and Trademark Office +.%D February 28, 1989 +.%N US Patent 4809168 +.Re +.Sh HISTORY +Passive serialization mechanism first appeared in +.Nx 6.0 . |