A less misleading intro to atomic::Ordering

[vorner]

This goes into more detail, but without suggesting misleading things. It
also tries to point out several footguns about atomic orderings.

Fixes#55196.

I'm not sure if I went too informal, though, or if the intro isn't too long. Suggestions to improvement are, of course, welcome.

[rust-highfive]

r? @aidanhs

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

[TimNN]

Ping from triage @aidanhs / @rust-lang/docs: This PR requires your review.

[GuillaumeGomez]

Please add all missing types/functions links.

[frewsxcv]

@GuillaumeGomez can you provide a resource or an example on how to do that?

[GuillaumeGomez]

@frewsxcv All docs have the old linking style. Or you can try the new one (just like you would import an item in most cases). For example:

pubfnfoo(){}/// I want to link to [`foo`]!pubfnbar(){}

In here, you'll generate a link to the foo function. You can also use it in a more "normal" way:

/// I want to link to [`foo`][foo]!pubfnbar(){}

[vorner]

For some reason, I had to provide the targets for the links, only naming the variants didn't seem to do anything.

Anyway, fixup with the links is there for review (I'll rebase and squash the fixups once the review is done, but I don't like doing history rewrites during).

[rust-highfive]

The job x86_64-gnu-llvm-5.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:end:08669ae5:start=1541184646133900578,finish=1541184700561242802,duration=54427342224
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout
Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#Pull-Requests-and-Security-Restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-5.0
---
[00:03:44] travis_fold:start:tidy
travis_time:start:tidy
tidy check
[00:03:44] tidy error: /checkout/src/libcore/sync/atomic.rs:183: line longer than 100 chars
[00:03:44] tidy error: /checkout/src/libcore/sync/atomic.rs:188: line longer than 100 chars
[00:03:44] tidy error: /checkout/src/libcore/sync/atomic.rs:199: line longer than 100 chars
[00:03:45] some tidy checks failed
[00:03:45] [00:03:45] [00:03:45] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:03:45] [00:03:45] [00:03:45] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:03:45] Build completed unsuccessfully in 0:00:49
[00:03:45] Build completed unsuccessfully in 0:00:49
[00:03:45] Makefile:79: recipe for target 'tidy' failed
[00:03:45] make: *** [tidy] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:2c64be39
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
---
travis_time:end:1c8c3918:start=1541184936739718010,finish=1541184936744694182,duration=4976172
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:0027ced0
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:0b0a1c20
travis_time:start:0b0a1c20
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:0b1048fc
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[frewsxcv]

From a readability perspective, this looks good to me, but I can't vouch for the correctness of the text. Can someone from @rust-lang/libs read this over?

[alexcrichton]

I would personally be wary of trying to include too much information about the specifics of memory orderings in our documentation, can we perhaps simply link to LLVM/C++ documentation? I would expect those to be thoroughly vetted and good sources to read up on, and because our model is the same that should suffice as well

[vorner]

So, would the way forward be to strip the original of the wrong information (making it terser) and maybe put something like this PR into nomicon or such place?

[alexcrichton]

That would my own personal preference, yes, although others may feel differently

[GuillaumeGomez]

@alexcrichton Seems like a good idea actually. Give an access to more information if you want it but remaining all about the type usage explanation. Yes, I really like it.

[vorner]

OK, I'll do the minimal version, then. Let's close this one.