Module Name: src
Committed By: riastradh
Date: Thu Feb 23 03:03:23 UTC 2023
Modified Files:
src/share/man/man9: pcq.9
Log Message:
pcq(9): Document memory ordering guarantees.
To generate a diff of this commit:
cvs rdiff -u -r1.8 -r1.9 src/share/man/man9/pcq.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/pcq.9
diff -u src/share/man/man9/pcq.9:1.8 src/share/man/man9/pcq.9:1.9
--- src/share/man/man9/pcq.9:1.8 Thu Feb 8 09:03:23 2018
+++ src/share/man/man9/pcq.9 Thu Feb 23 03:03:23 2023
@@ -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
