Fixup Atomic*::from_ptr safety docs

[WaffleLapkin]

See #115719 (comment)
cc @RalfJung

[rustbot]

r? @cuviper

(rustbot has picked a reviewer for you, use r? to override)

[RalfJung]

Thanks!

Reading the text, I am also confused by this:

/// * Non-atomic accesses to the value behind `ptr` must have a happens-before relationship
/// with atomic accesses via the returned value (or vice-versa).

What does it mean to have a happens-before relationship "via the return value"? Happens-before is a partial order on memory operations, it does not go "via values".

[tgross35]

Thanks for doing this directly Waffle, easier than me guessing around

[tgross35]

Reading the text, I am also confused by this:

/// * Non-atomic accesses to the value behind `ptr` must have a happens-before relationship
/// with atomic accesses via the returned value (or vice-versa).

What does it mean to have a happens-before relationship "via the return value"? Happens-before is a partial order on memory operations, it does not go "via values".

This is referring to the return value of the function, i.e. always-atomic accesses via the returned AtomicX

[RalfJung]

Oh, it's "happens before with (atomic access via return value)", I see. Is that part necessary? Why can't we just say, any non-atomic and atomic accesses to the memory ptr points to must have a happens-before relationship?

[tgross35]

I adapted it from #115719 (comment), but maybe that statement could just be combined with the first point under it?

Maybe these docs should just have suggest the default "don't use nonatomically for 'a and don't mix sizes" since that works for most users, then point to the nomicon for the more detailed version (when things need to be Sync / what the memory model is). Or document this all in std::sync::atomic and refer to that. It just seems a bit weird to put in-depth documentation of atomic semantic nuances on a single method when it is a really a more broad topic.

[RalfJung]

Yeah I agree. Module-level docs seem better.

[WaffleLapkin]

Hm, so the module docs solution would be something like this?

//! ## Overlapping accesses
//!
//! blah blah blah bad
//!
//! ## Mixing atomic and non-atomic operations
//!
//! blah blah blah, be careful

/// ## Safety
///
/// * ...
/// * See also documentation on [overlapping accesses][self#Overlapping-accesses] and [mixing atomic and non-atomic operations][self#Mixing-atomic-and-non-atomic-operations], this method does not allow you to violate the rules described there, it's still UB
fn from_pt()

[RalfJung]

We should probably have something like

## Memory model for atomic accesses

Rust atomics currently follow the same rules as [C++20 atomics](https://en.cppreference.com/w/cpp/atomic), 
specifically atomic_ref. Basically, creating a shared reference to one of the Rust atomic types corresponds to 
creating an atomic_ref in C++; the atomic_ref is destroyed when the lifetime of the shared reference ends. 
(A Rust atomic type that is exclusively owned or behind a mutable reference does not correspond to an 
“atomic object” in C++, since it can be accessed via non-atomic operations.)

(I think all the text that used to follow the above paragraph should probably go above this new 
subsection? Except for the part about `Ordering`, that one should go into the model section.)

Since C++ does not support mixing atomic and non-atomic accesses, or non-synchronized 
different-sized accesses to the same data, Rust does not support those operations either. (more text here)

Turns out "imperfectly overlapping" and "different size" are equivalent due to the strong alignment requirements, so it's probably easier to just talk about mixed-size accesses than trying to talk about imperfect overlap more general.

[RalfJung]

@rustbot author

[WaffleLapkin]

I don't particularly like my wording or the examples, but I also sleepy, so can't come up with anything better. @rustbot review

[RalfJung]

Suggested change

	/// * You must adhere to the [Memory model for atomic accesses].
	/// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not allowed to
	/// mix atomic and non-atomic accesses, or atomic accesses of different sizes, without synchronization.

[RalfJung]

That's great, thanks! I think I'd leave a very short one-sentence summary of the surprising parts of the memory model at each of these functions, but otherwise LGTM.

@rustbot author

[WaffleLapkin]

@RalfJung I've applied changes you proposed.

@oskgo your proposed change does not actually have a read-read conflict, I've added a similar example.

@rustbot review

[RalfJung]

Looks good, thanks. :)
@bors r+ rollup

[bors]

📌 Commit 1023845 has been approved by RalfJung

It is now in the queue for this repository.