[src/netbsd-7]: src/share/man/man9 Pull up following revision(s) (requested b...

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

details:   https://anonhg.NetBSD.org/src/rev/45e1a84d8d94
branches:  netbsd-7
changeset: 799115:45e1a84d8d94
user:      snj <snj%NetBSD.org@localhost>
date:      Wed Mar 18 08:46:32 2015 +0000

description:
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.

diffstat:

 share/man/man9/pserialize.9 |  85 ++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 76 insertions(+), 9 deletions(-)

diffs (111 lines):

diff -r 3e7fa52277b7 -r 45e1a84d8d94 share/man/man9/pserialize.9
--- a/share/man/man9/pserialize.9       Wed Mar 18 08:36:44 2015 +0000
+++ b/share/man/man9/pserialize.9       Wed Mar 18 08:46:32 2015 +0000
@@ -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 @@
 .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