Module Name: src
Committed By: snj
Date: Wed Mar 18 08:46:32 UTC 2015
Modified Files:
src/share/man/man9 [netbsd-7]: pserialize.9
Log Message:
Pull up following revision(s) (requested by riastradh in ticket #607):
share/man/man9/pserialize.9: revisions 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.20.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.20.1
--- src/share/man/man9/pserialize.9:1.3 Sun Aug 7 12:29:24 2011
+++ src/share/man/man9/pserialize.9 Wed Mar 18 08:46:32 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.20.1 2015/03/18 08:46:32 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
