From eecba6ae71da5a00049dc36724e99542952de81e Mon Sep 17 00:00:00 2001
From: riastradh <riastradh@NetBSD.org>
Date: Thu, 23 Feb 2023 03:03:23 +0000
Subject: [PATCH] pcq(9): Document memory ordering guarantees.

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

diff --git a/share/man/man9/pcq.9 b/share/man/man9/pcq.9
index 3aec95dc57a1..9d14cd6e492b 100644
--- a/share/man/man9/pcq.9
+++ b/share/man/man9/pcq.9
@@ -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 @@ otherwise, return
 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