[src/trunk]: src/share/man/man9 pcq(9): Document memory ordering guarantees.

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

details:   https://anonhg.NetBSD.org/src/rev/316267834508
branches:  trunk
changeset: 373659:316267834508
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Thu Feb 23 03:03:23 2023 +0000

description:
pcq(9): Document memory ordering guarantees.

diffstat:

 share/man/man9/pcq.9 |  59 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 58 insertions(+), 1 deletions(-)

diffs (73 lines):

diff -r fc12a1ddd3cb -r 316267834508 share/man/man9/pcq.9
--- a/share/man/man9/pcq.9      Thu Feb 23 03:01:49 2023 +0000
+++ b/share/man/man9/pcq.9      Thu Feb 23 03:03:23 2023 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: pcq.9,v 1.8 2018/02/08 09:03:23 dholland Exp $
+.\"     $NetBSD: pcq.9,v 1.9 2023/02/23 03:03:23 riastradh Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -118,6 +118,63 @@
 The item must not have the value of
 .Dv NULL .
 .El
+.Ss Memory ordering
+Any memory operations sequenced before
+.Fn pcq_put
+of an item in one thread happen before all memory operations with data
+dependencies on the item returned by
+.Fn pcq_get
+or
+.Fn pcq_peek
+in another thread.
+For example:
+.Bd -literal -offset indent
+int mumble;
+
+/* producer */
+mumble = 42;                   // A
+foo->x = 123;                  // B
+refcnt = foo->refcnt;          // C
+pcq_put(pcq, foo);
+KASSERT(refcnt == 0);
+
+/* consumer */
+foo = pcq_get(pcq);
+if (foo == NULL)
+       return;
+atomic_inc_uint(&foo->refcnt); // D
+x = foo->x;                    // E
+if (x == 123)
+       KASSERT(mumble == 42);  // F
+.Ed
+.Pp
+In this example, memory operations B and C happen-before D and E.
+However, no ordering is guaranteed for A or F relative to any other
+memory operations, because the memory location of
+.Fa mumble
+is independent of the pointer
+.Fa foo
+returned by
+.Fn pcq_get .
+.Pp
+If you must guarantee A happens before F, then on the consumer side,
+after
+.Fn pcq_get
+or
+.Fn pcq_peek ,
+you can call
+.Fn membar_acquire
+to turn it into an acquire operation instead of a consume operation;
+.Fn pcq_put
+serves as the matching release operation.
+.Po
+This is a little dicey.
+Perhaps there should be separate
+.Fn pcq_peek_acq
+and
+.Fn pcq_get_acq
+operations if this semantics is necessary.
+.Pc
 .Sh CODE REFERENCES
 The
 .Nm