add documentation for atomics

[andrewrk]

moved from #367

• @fence
• @cmpxchgStrong and @cmpxchgWeak
• @atomicRmw
• builtin atomic memory ordering enum
  • mention Shortcut (type inferrence) for naming enum values #683
• explain when to use atomics and when to use volatile
• talk about data races and multithreaded programming
• talk about lock free programming

[nacho00112]

I need this, I wasn't able to understand it reading the documentations of other languages,
they have a lot of different stuff like memory order consume, relaxed and seq_cst

[nacho00112]

If someone need this, I recommend this article: https://dev.to/kprotty/understanding-atomics-and-memory-ordering-2mom

[Pyrolistical]

Both @cmpxchgStrong and @cmpxchgWeak seem to have incorrect documentation.

returning null if the current value is not the given expected value.

That does not match the code snippet:

fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_value: T) ?T {
    const old_value = ptr.*;
    if (old_value == expected_value) {
        ptr.* = new_value;
        return null;
    } else {
        return old_value;
    }
}

Assuming the code snippet is correct, then should it read:

returning the current value if it is not the given expected value.