ziglang
langref: describe memory model and atomic orders
EDIT: Some motivation: The point of a reference is to describe the language succinctly and accurately, without saying only "go read the formal specification". LLVM's description of the memory model, which we are currently linking to, is verbose and scattered over multiple pages. The description in this PR is more structured and much more concise, without any oversimplification.
I'm not a core member, but I would like to add my two cents. This is a very sensitive topic that requires an extremely rigorous definition, which the cppreference already provides. In my experience, trying to "simplify" the definition creates certain inconsistencies and should be reserved for blog posts and articles, not language references.
Yeah, I'm not too keen on trying to specify the (frankly very complicated) C++ memory model in the language reference, especially when we don't yet know if Zig will actually keep this memory model for the long term. Even Rust doesn't try to do this.
IMO, what we should do is simply state that Zig currently inherits the LLVM/C++11 memory model, but that this may change before 1.0. For each type of memory ordering, we could link to the relevant LLVM documentation section and cppreference section, and leave it at that.
I think the language reference should stand on its own and provide a decent description even for features that are currently implemented by a dependency, particularly as we are gaining backends that do not use the LLVM dependency.
Note that the memory model of C and C++ is significantly more subtle than that of LLVM, so the comparison to cppreference is largely irrelevant. In particular, C/C++ have the notion of consume, which Clang just treats as the simpler acquire. I believe I have not modified the meaning of LLVM's definitions nor omitted important information.
I think the language reference should stand on its own and provide a decent description even for features that are currently implemented by a dependency
I'm not sure I buy this argument. What about e.g. floating point semantics? Where would we draw the line?
I think it's fine to reference a third-party spec when the Zig language is just providing an implementation of that spec, as opposed to actually defining it authoritatively.
The cppreference, the Rust std docs and the Nomicon describe the memory model but not IEEE754 floats.
IEEE754 has become a de-facto standard for most high- and low-level programming languages in use today, while the majority of languages out there do not expose a memory model of "just what LLVM does".
Also note that the language reference isn't defining anything authoritatively. That will be the job of the specification, which will define the memory model formally—or defer to LLVM—for implementers and tool authors. The reference should give common users a precise but fast-to-acquire understanding of the language, and I believe LLVM's specification is too formal and scattered to do that.