Improve the documentation of atomic::fence

[matthieu-m]

Attempt to "fix" two flaws of the current documentation:

1. The over-emphasis of fence - fence synchronization, relegating atomic - fence and fence - atomic synchronization to second fiddle.
2. The lack of explanation as to how to properly perform atomic - fence and fence - atomic synchronization.

It does so by first making it clear that there are 3 different ways to use an atomic fence, then presenting a full example for each usecase, noting the particular position of the fence with regard to the atomic operation, and rounding up with generic notes.

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Mark-Simulacrum]

Maybe we can copy the cppreference on this?

https://en.cppreference.com/w/cpp/atomic/atomic_thread_fence.html

In particular, this language seems to miss "Y reads the value written by X (or the value would be written by release sequence headed by X if X were a release operation)" -- it's sort of implied by the example, but stating it explicitly feels better. It's also maybe obvious (otherwise it's not clear what would establish a relation between a particular release operation and particular acquire fence), but having a precise rule set seems better than prose? I find the bullets in the reference relatively easier to read than the language here.

[Mark-Simulacrum]

(I'm not sure what license that language is under, so copying may not be an option).

[matthieu-m]

Interesting. I tend to find the language on cppreference too "formal" for my taste.

I would say for me it's the difference between the "Guide-level" and "Reference-level" portions of Rust RFCs: the language here is guide-level, whereas the explanation on cppreference is reference-level, a formal specification of sort.

I do think having a "formal" specification is a good thing, but I find the esoteric language makes it hard to approach, and raises more questions than it answers -- what's a "release sequence headed by"? -- and thus I much prefer the Rust documentation (on fence, or Ordering) as it's so much more approachable, due to its use of familiar language.

---

With the ongoing work on the Rust specification, may I suggest leaving a more familiar language in the documentation, and later on linking to the specification for the more formal definition?

This way we can have our cake and eat it too.

[Mark-Simulacrum]

Suggested change

	/// An atomic operation 'X' with (at least) [`Release`] ordering semantics on some atomic object
	/// 'm' on thread 1 is paired on thread 2 with an atomic read 'Y' with any order on 'm' followed by
	/// a fence 'B' with (at least) [`Acquire`] ordering semantics. This provides a happens-before
	/// dependence between X and B.
	/// * An atomic operation 'X' with (at least) [`Release`] ordering semantics on some atomic object
	/// 'm' on thread 1 is paired with
	/// * an atomic read 'Y' on thread 2 with any order on 'm'
	//// * followed by a fence 'B' with (at least) [`Acquire`] ordering semantics.
	/// This provides a happens-before dependence between X and B.

Can we reformat something like this for the statements? I think splitting it up help make the readability better.

[matthieu-m]

I love the idea of introducing structure to better highlight the various steps.

I wasn't quite sure how to introduce structure, so I've structured each of the 3 "chapters" in a slightly different way.

I personally prefer the 3rd way (fence-fence) which clearly isolates the operation on either thread, while I feel that the 1st way (atomic-fence) which puts the "on thread1" and "is paired on thread 2" in the steps is the less clear.

I'm looking forward to your opinion, and suggestions.

[Mark-Simulacrum]

I think 3rd way seems good to me. Let's update to use that style and then I think it'll be good to merge.

[matthieu-m]

@rustbot review

[matthieu-m]

@rustbot review

I've also aligned the wording more closely between the 3 paragraphs. There were egregious uses of load/store for the Relaxed operations which could confuse the reader. Relaxed operations now use the read/write wording instead, making it clear that both load/store and RMW operations work just as well.

(This is closer to the wording used on cppreference, which use read/written with regard to the values, not loaded/stored)

[Mark-Simulacrum]

r=me with commits squashed

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[matthieu-m]

@rustbot r=Mark-Simulacrum

[Mark-Simulacrum]

@bors r=Mark-Simulacrum

[bors]

📌 Commit 5431c6f has been approved by Mark-Simulacrum

It is now in the queue for this repository.