make C++ atomic opt in via -d:nimUseCppAtomics (#24209)

refs #24207

The `-d:nimUseCAtomics` flag added in #24207 is now inverted and made
into `-d:nimUseCppAtomics`, which means C++ atomics are only enabled
with the define. This flag is now also documented and tested.

changelog.md

@@ -62,6 +62,9 @@
     (were `int32`, are now `uint32`)
   - `n_net` field of `Tnetent` (was `int32`, is now `uint32`)
 
+- The `Atomic[T]` type on C++ now uses C11 primitives by default instead of
+  `std::atomic`. To use `std::atomic` instead, `-d:nimUseCppAtomics` can be defined.
+
 
 ## Standard library additions and changes
 

lib/pure/concurrency/atomics.nim

@@ -10,6 +10,9 @@
 ## Types and operations for atomic operations and lockless algorithms.
 ##
 ## Unstable API.
+## 
+## By default, C++ uses C11 atomic primitives. To use C++ `std::atomic`,
+## `-d:nimUseCppAtomics` can be defined.
 
 runnableExamples:
   # Atomic
@@ -50,7 +53,7 @@ runnableExamples:
   flag.clear(moRelaxed)
   assert not flag.testAndSet
 
-when (defined(cpp) and not defined(nimUseCAtomics)) or defined(nimdoc):
+when (defined(cpp) and defined(nimUseCppAtomics)) or defined(nimdoc):
   # For the C++ backend, types and operations map directly to C++11 atomics.
 
   {.push, header: "<atomic>".}

tests/stdlib/concurrency/tatomics.nim

@@ -1,5 +1,7 @@
 discard """
-  matrix: "--mm:refc; --mm:orc"
+  # test C with -d:nimUseCppAtomics as well to check nothing breaks
+  matrix: "--mm:refc; --mm:orc; --mm:refc -d:nimUseCppAtomics; --mm:orc -d:nimUseCppAtomics"
+  targets: "c cpp"
 """
 
 # test atomic operations

tests/stdlib/concurrency/tatomics_size.nim

@@ -1,5 +1,6 @@
 discard """
-  matrix: "--mm:refc; --mm:orc"
+  # test C with -d:nimUseCppAtomics as well to check nothing breaks
+  matrix: "--mm:refc; --mm:orc; --mm:refc -d:nimUseCppAtomics; --mm:orc -d:nimUseCppAtomics"
   targets: "c cpp"
 """
 import std/atomics
@@ -17,4 +18,4 @@ block testSize: # issue 12726
       f: AtomicFlag
   static:
     doAssert sizeof(Node) == sizeof(pointer)
-    doAssert sizeof(MyChannel) == sizeof(pointer) * 2
+    doAssert sizeof(MyChannel) == sizeof(pointer) * 2