Document memory model of Per-field atomics

[Seelengrab]

As the docs say, this will be published "later":

Specific details of the memory model and other details of the design are written in the Julia Atomics Manifesto, which will later be published formally.

Per-field atomics

Additionally, the linked manifesto has a number of TODOs that may or may not have been decided by now (I hope they are - some of them seem to be concerned with how this will be/is implemented..). 1.7 will have been released for 1 year in just about 3 months as of opening of this issue, so getting that done would probably be good.

[KristofferC]

I don't think this is release blocking.

[Seelengrab]

I think this got tagged with 1.9 as a kind of "forget me not", precisely because this is a core language feature that users should be able to rely on, with documentation supporting it. I fear that this issue will, like so many others tagged with doc, linger on and on - except it's worse in this case, since it's a core language feature and not some not-so-clear docstring of a minor function. Without that documentation, how are users supposed to rely on the semantics introduced by that feature?

[StefanKarpinski]

Who is the right person to document this? Presumably @vtjnash (who I've already assigned).

[Seelengrab]

Probably, yeah, since he's the original author of the manifesto & main implementer of this? I'd offer to write it up, but I have no clue how this is implemented, what considerations were used in the implementation, what changed from manifesto to implementation etc.. Though educational, reverse engineering would probably take considerably longer and some important part would probably be missed 🤷

[Seelengrab]

This has come up on discourse: https://discourse.julialang.org/t/calling-max-atomically-on-a-compound-type/94028?u=sukera

[MasonProtter]

Bump. It's now 2025, we're probably close to releasing v1.12 and we still have a situation where the docstring for @atomic (added in 1.7) is only useful or informative for people who already know all about this stuff, not for anyone who wants to learn to use it.

If you do want to learn to use it, here's the wild goose chase you get sent on:

• Try to read the docstring. The docstring is rather long but doesn't explain what the ordering symbols mean.
  • the docstring tells you to visit the per field atomics section of the docs. Those docs don't explain anything. They just
    • point towards the per field atomics manifesto, which also doesn't explain them in any detail, instead
      • pointing to some Rust documentation that isn't particularly great if you don't know Rust.