CVS commit: [netbsd-10] src

["Martin Husemann" <martin%netbsd.org@localhost>]

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.