Module Name: src Committed By: snj Date: Tue Mar 24 09:11:20 UTC 2015
Modified Files: src/share/man/man9 [netbsd-6]: pserialize.9 Log Message: Pull up following revision(s) (requested by riastradh in ticket #1270): share/man/man9/pserialize.9: revision 1.4-1.8 Expand pserialize(9) example to include publish, read, and destroy. -- Bump date. -- Fix typo: pserialize_read_exit(s), not s = pserialize_read_exit(). -- Elaborate comment before pserialize_perform. -- Use membar_consumer until we have membar_datadep_consumer. To generate a diff of this commit: cvs rdiff -u -r1.3 -r1.3.4.1 src/share/man/man9/pserialize.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/share/man/man9/pserialize.9 diff -u src/share/man/man9/pserialize.9:1.3 src/share/man/man9/pserialize.9:1.3.4.1 --- src/share/man/man9/pserialize.9:1.3 Sun Aug 7 12:29:24 2011 +++ src/share/man/man9/pserialize.9 Tue Mar 24 09:11:20 2015 @@ -1,4 +1,4 @@ -.\" $NetBSD: pserialize.9,v 1.3 2011/08/07 12:29:24 rmind Exp $ +.\" $NetBSD: pserialize.9,v 1.3.4.1 2015/03/24 09:11:20 snj Exp $ .\" .\" Copyright (c) 2011 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -24,7 +24,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd July 30, 2011 +.Dd November 21, 2014 .Dt PSERIALIZE 9 .Os .Sh NAME @@ -74,18 +74,85 @@ Operation blocks and it may only be perf .El .\" ----- .Sh EXAMPLES -Typical code fragment in the writer side: +Given a global database of frotz records: .Bd -literal - mutex_enter(\*[Am]writer_psz_lock); + struct frotz { + ... + struct frotz *f_next; + }; + + kmutex_t frobbotzim_lock; + struct frotz *frobbotzim; + pserialize_t frobbotzim_psz; +.Ed +.Pp +Create a frotz and publish it, as a writer: +.Bd -literal + struct frotz *f = pool_get(\*[Am]frotz_pool, PR_WAITOK); + + /* Initialize f. */ + ... + + mutex_enter(\*[Am]frobbotzim_lock); + f->f_next = frobbotzim; /* - * Perform the updates (e.g. remove data items from a list). + * Publish the contents of f->f_next before we publish the + * pointer to f in frobbotzim. */ - ... - pserialize_perform(object-\*[Gt]psz); + membar_producer(); + frobbotzim = f; + mutex_exit(\*[Am]frobbotzim_lock); +.Ed +.Pp +Find a frotz, as a reader: +.Bd -literal + struct frotz *f; + int error = ENOENT; + int s; + + s = pserialize_read_enter(); + for (f = frobbotzim; f != NULL; f = f->f_next) { + /* Fetch f before we fetch anything f points to. */ + membar_consumer(); + if (f->f_... = key) { + *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(\*[Am]frobbotzim_lock); + for (fp = \*[Am]frobbotzim; (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; + } + } /* - * At this point it is safe to destroy old data items. + * Wait for all existing readers to complete. New readers will + * not see f because the list no longer points to it. */ - mutex_exit(\*[Am]writer_psz_lock); + pserialize_perform(frobbotzim_psz); + /* Now nobody else can be touching f, so it is safe to free. */ + mutex_exit(\*[Am]frobbotzim_lock); + + if (f != NULL) + pool_put(\*[Am]frotz_pool, f); .Ed .\" ----- .Sh CODE REFERENCES