[src/trunk]: src/share/man/man9 Expand pserialize(9) example to include publi...

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e523e8cf79f9
branches:  trunk
changeset: 333902:e523e8cf79f9
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Fri Nov 21 15:28:33 2014 +0000

description:
Expand pserialize(9) example to include publish, read, and destroy.

diffstat:

 share/man/man9/pserialize.9 |  83 +++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 73 insertions(+), 10 deletions(-)

diffs (100 lines):

diff -r aa982df22494 -r e523e8cf79f9 share/man/man9/pserialize.9
--- a/share/man/man9/pserialize.9       Fri Nov 21 13:31:19 2014 +0000
+++ b/share/man/man9/pserialize.9       Fri Nov 21 15:28:33 2014 +0000
@@ -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 @@
 .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);
-       /*
-        * At this point it is safe to destroy old data items.
-        */
-       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