Content-Disposition: inline
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset="US-ASCII"
MIME-Version: 1.0
Date: Sun, 30 Jul 2023 12:13:02 +0000
From: "Martin Husemann" <martin@netbsd.org>
Subject: CVS commit: [netbsd-10] src
To: source-changes@NetBSD.org
Approved: for-source-only
Reply-To: martin@netbsd.org
Message-Id: <20230730121302.960E2FBDB@cvs.NetBSD.org>

Module Name:	src
Committed By:	martin
Date:		Sun Jul 30 12:13:02 UTC 2023

Modified Files:
	src/share/man/man9 [netbsd-10]: pcq.9
	src/sys/kern [netbsd-10]: subr_pcq.c

Log Message:
Pull up following revision(s) (requested by riastradh in ticket #263):

	share/man/man9/pcq.9: revision 1.9
	sys/kern/subr_pcq.c: revision 1.14
	sys/kern/subr_pcq.c: revision 1.15
	sys/kern/subr_pcq.c: revision 1.16
	sys/kern/subr_pcq.c: revision 1.17
	sys/kern/subr_pcq.c: revision 1.18
	sys/kern/subr_pcq.c: revision 1.19

pcq(9): Make pcq_put a release operation, in memory ordering.

Otherwise, for example, the following assertion could fail:
        /* publisher */
        nusers = foo->nusers;
        pcq_put(pcq, foo);
        KASSERT(nusers == 0);
        /* user */
        foo = pcq_get(pcq);
        if (foo != NULL)
                atomic_inc_uint(&foo->nusers);

pcq(9): Fix consume operation in pcq_peek/get.

These use atomic_load_consume to match the atomic_store_release in
pcq_put for pcq->pcq_items[c].

Reading the snapshot of pcq->pcq_pc need not be ordered:
- The consumer side (pcq_peek/get) is serialized by the API contract
  (single-consumer, multi-producer), so no ordering is necessary.
- The producer side updates pcq->pcq_pc first; if the consumer side
  sees that before the producer side has stored pcq->pcq_items[c],
  there's no problem -- it's as if the consumer had happened just a
  moment earlier and the producer hadn't entered pcq_put yet.

However, it should be an atomic load, not a plain load.  So use
atomic_load_relaxed, if for no other reason than to pacify thread
sanitizers.

pcq(9): Explain why store need not be atomic in pcq_get.
No functional change intended.

pcq(9): Explain why membar_release isn't needed in pcq_get.
No functional change intended.

pcq(9): Document memory ordering guarantees.

pcq(9): Sketch correctness proof for some critical properties.
No functional change intended.

pcq(9): KASSERT(A && B) -> KASSERT(A); KASSERT(B)


To generate a diff of this commit:
cvs rdiff -u -r1.8 -r1.8.14.1 src/share/man/man9/pcq.9
cvs rdiff -u -r1.13 -r1.13.18.1 src/sys/kern/subr_pcq.c

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.