Module Name: src
Committed By: riastradh
Date: Fri Nov 21 15:28:33 UTC 2014
Modified Files:
src/share/man/man9: pserialize.9
Log Message:
Expand pserialize(9) example to include publish, read, and destroy.
To generate a diff of this commit:
cvs rdiff -u -r1.3 -r1.4 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.4
--- src/share/man/man9/pserialize.9:1.3 Sun Aug 7 12:29:24 2011
+++ src/share/man/man9/pserialize.9 Fri Nov 21 15:28:33 2014
@@ -1,4 +1,4 @@
-.\" $NetBSD: pserialize.9,v 1.3 2011/08/07 12:29:24 rmind Exp $
+.\" $NetBSD: pserialize.9,v 1.4 2014/11/21 15:28:33 riastradh Exp $
.\"
.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -74,18 +74,81 @@ 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);
- /*
- * Perform the updates (e.g. remove data items from a list).
- */
+ 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. */
...
- pserialize_perform(object-\*[Gt]psz);
+
+ mutex_enter(\*[Am]frobbotzim_lock);
+ f->f_next = frobbotzim;
/*
- * At this point it is safe to destroy old data items.
+ * Publish the contents of f->f_next before we publish the
+ * pointer to f in frobbotzim.
*/
- mutex_exit(\*[Am]writer_psz_lock);
+ 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) {
+.\" membar_datadep_consumer();
+ if (f->f_... = key) {
+ *resultp = f->f_...;
+ error = 0;
+ break;
+ }
+ }
+ s = pserialize_read_exit();
+
+ 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;
+ }
+ }
+ /* Wait for all existing readers to drain. */
+ 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
