nomicon

nomicon copied to clipboard

Rendered

This PR is for my attempted rewrite of the atomics section of the Nomicon, to give it a more spec-focused explanation and avoid misconceptions like time and reordering. Currently it’s far from finished, containing only an explanation of multi-threaded execution and the start of the “relaxed” section, but I’m opening this PR for early review and feedback on the explanation method.

Reading order:

1. atomics.md
2. multithread.md
3. relaxed.md
4. acquire-release.md
5. seqcst.md
6. fences.md

Edit: I now see that copyright means this won’t work, so I’ve removed it.

I also copy-pasted in the C++ spec, but changed a couple things, due things like the lack of consume and sig_atomic_t:

• I removed the definition of “dependency carrying”
• I removed definition of “depedency-ordered before”
• I removed the definition of “inter-thread happens before”
• I removed the happens-before cycle restriction, since “This cycle would otherwise be possible only through the use of consume operations.”
• I replaced the definition of “happens before” with the definition of “simply happens before” (since “In the absence of consume operations, the happens before and simply happens before relations are identical”)
• I removed the volatile sig_atomic_t exception
• I rewrote memory_order as core::sync::atomic::Ordering
• I removed kill_dependency
• I renamed atomic_thread_fence to fence and atomic_signal_fence to compiler_fence, as it is called in std

I’m not certain about the copyright of this — ISO says that they only hold copyright over published versions, but I couldn’t find information about copyright of drafts.

I’m not certain about the copyright of this — ISO says that they only hold copyright over published versions, but I couldn’t find information about copyright of drafts.

https://en.cppreference.com/w/cpp/language/memory_model and https://en.cppreference.com/w/cpp/atomic/memory_order#Formal_description paraphrase the relevant parts of the C++ spec, and are CC-BY-SA and GFDL dual-licensed. See What can I do with the material on this site?.

Given that my free time has been reduced since I’ve started this PR and the signals section (which I was part way through writing) is a mostly different area of expertise to the rest of atomics, I'm going to mark this as ready to review now.

Open questions:

• Are Unicode diagrams the best format? Do they display correctly on all devices? Would it even be possible to use a different format?
• CI is red because Rust’s std docs now link to the broken link atomics.html (which is now atomics/atomics.html) — what can be done about this?

cc @cbeuw for fact-checking since you seem to be an expert on the model (only if you have time of course).

I have now rendered this PR for easier review.

This looks absolutely amazing! The Unicode diagrams are nicely rendered on both my Mac and Android phone, and are very pretty. This may well be the best tutorial on C++ memory model out there, including all the ones I've seen targeting C++ exclusively.

I definitely wouldn't call myself a weak memory expert, considering whenever I work with it I always come up with new questions instead of being able to tell the definite behaviours (but this may be a good thing sometimes). Unfortunately for me, the next 3 months will be extremely busy. I won't be able to go through it in detail, but I'll have my eye on it from time to time, both now and after it's been merged. There will almost certainly be extremely subtle errors given the topic's nature, but that shouldn't prevent this from going live.

I have minor rendering issues with the diagrams on Linux (in both Firefox and Chromium):

I suggest replacing them with inline SVG or separate image files.

From Issue #104814 on Rust:

[…] it should be clarified whether the difference between the Rust documentation and the C++20 reference exists intentionally, i.e. is Rust deliberately giving less guarantees to the programmer than the C++20 standard does? (Even though still following the C++20 memory model in practice "as of now".)

I have been told that the C++20 reference takes precedence over Rust's documentation, but wanted to raise this issue nonetheless as it may be relevant for future backward compatibility.

What is the status here? 👀

This is in my queue to review, but I have 100+ PRs in that queue, and this one is quite large and a challenging topic. Realistically I probably won't get to it soon.

In the meantime, I recommend people check out Mara's book at https://marabos.nl/atomics/ which is now free.

EDIT to add: To be clear, I very much want to see this land. I just may not be able to make time for it for a while.

@ehuss do you still have too much in the review queue?

I just pushed a commit to fix the incorrect claim that one needs 4 threads to observe the difference between SeqCst and AcqRel, which was a misunderstanding I had. I also changed the example that shows the need for SeqCst to a simpler one that only uses two threads.

The changed sections include the SeqCst chapter and the part on SeqCst fences. Thanks @ibraheemdev for pointing this out!

@ehuss it seems like people with expertise in atomics have given this a look by now. so I think it would just need an editorial review from you, which is hopefully quicker than a technical one (it takes some time still of course, and I don't expect you to take a look at this very soon, but just FYI)

We discussed this in the lang-docs call today. Thanks to everyone here for the reviews and the feedback, and to @SabrinaJewson for this work. We're trying to have a look at this. Even just editorially, it's an impressive body of work and may take some time. Thanks for bearing with us.