Deprecate atomic compare exchange strong and improve doc (#594)

* Improve documentation of atomic_[compare_]exchange

* Fixup atomic_{load,store}

* Fix typo retur[n]s

Co-authored-by: Dong Hun Lee <[email protected]>

---------

Co-authored-by: Dong Hun Lee <[email protected]>

docs/source/API/core/atomics/atomic_compare_exchange.rst

@@ -4,31 +4,34 @@
 .. role:: cppkokkos(code)
    :language: cppkokkos
 
-Header File: <Kokkos_Core.hpp>
+Defined in header ``<Kokkos_Atomic.hpp>`` which is included from ``<Kokkos_Core.hpp>``
 
 Usage
 -----
 
 .. code-block:: cpp
 
-   old_val = atomic_compare_exchange(ptr_to_value,
-				     comparison_value,
-				     new_value);
+   auto old = atomic_compare_exchange(&obj, expected, desired);
 
-Atomically sets the value at the address given by ``ptr_to_value`` to ``new_value`` if the current value at ``ptr_to_value``
-is equal to ``comparison_value``, and returns the previously stored value at the address independent on whether
-the exchange has happened.
+Atomically compares the current value of ``obj`` with ``expected``,
+replaces its value with ``desired`` if equal, and
+always returns the previously stored value at the address ``&obj`` regardless of whether the exchange has happened or not.
 
 Description
 -----------
 
-.. cppkokkos:function:: template<class T> T atomic_compare_exchange(T* const ptr_to_value, const T comparison_value, const T new_value);
+.. cppkokkos:function:: template<class T> T atomic_compare_exchange(T* ptr, std::type_identity_t<T> expected, std::type_identity_t<T> desired);
 
-   Atomically executes ``old_value = *ptr_to_value; if(old_value==comparison_value) *ptr_to_value = new_value; return old_value;``,
-   where ``old_value`` is the value at address ``ptr_to_value`` before doing the exchange.
+   Atomically compares ``*ptr`` with ``expected``, and if those are bitwise-equal, replaces the former with ``desired``, and always returns the actual value that was pointed to by ``ptr`` before the call.
 
-   :param ptr_to_value: address of the value to be updated
+   ``{ old = *ptr; if (old == expected) *ptr = desired; return old; }``
 
-   :param comparison_value: value to be compared to
+   :param ptr: address of the object to test and to modify
+   :param expected: value expected to be found in the object
+   :param desired: the value to store in the object if as expected
+   :returns: the value held previously by the object pointed to by ``ptr``
 
-   :param new_value: new value
+
+See also
+--------
+* `atomic_exchange <atomic_exchange.html>`_: atomically replaces the value of the referenced object and obtains the value held previously

docs/source/API/core/atomics/atomic_compare_exchange_strong.rst

@@ -1,33 +1,41 @@
 ``atomic_compare_exchange_strong``
 ==================================
 
+.. warning::
+   Deprecated since Kokkos 4.5,
+   use `atomic_compare_exchange <atomic_compare_exchange.html>`_ instead.
+
 .. role:: cppkokkos(code)
    :language: cppkokkos
 
-Header File: <Kokkos_Core.hpp>
+Defined in header ``<Kokkos_Atomic.hpp>`` which is included from ``<Kokkos_Core.hpp>``
 
 Usage
 -----
 
 .. code-block:: cpp
 
-   bool was_exchanged = atomic_compare_exchange_strong(ptr_to_value,
-						       comparison_value,
-						       new_value);
+   bool was_exchanged = atomic_compare_exchange_strong(&obj, expected, desired);
+   //                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   //                   deprecated since Kokkos 4.5
+   //                   instead prefer
+   //                   expected == atomic_compare_exchange(&obj, expected, desired)
 
-Atomically sets the value at the address given by ``ptr_to_value`` to ``new_value`` if the current value at ``ptr_to_value``
-is equal to ``comparison_value``, and returns true if the exchange has happened.
+Atomically compares the current value of ``obj`` with ``expected``
+and replaces its value with ``desired`` if equal.
+The function returns ``true`` if the exchange has happened, ``false`` otherwise.
 
 Description
 -----------
 
-.. cppkokkos:function:: template<class T> bool atomic_compare_exchange_strong(T* const ptr_to_value, const T comparison_value, const T new_value);
-
-   Atomically executes ``old_value = *ptr_to_value; if(old_value==comparison_value) *ptr_to_value = new_value; return old_value==comparison_value;``,
-   where ``old_value`` is the value at address ``ptr_to_value`` before doing the exchange.
+.. cppkokkos:function:: template<class T> bool atomic_compare_exchange_strong(T* ptr, std::type_identity_t<T> expected, std::type_identity_t<T> desired);
 
-   :param ptr_to_value: address of the value to be updated
+   Atomically compares ``*ptr`` with ``expected``, and if those are bitwise-equal, replaces the former with ``desired``.
+   If ``desired`` is written into ``*ptr`` then ``true`` is returned.
 
-   :param comparison_value: value to be compared to
+   ``if (*ptr == expected) { *ptr = desired; return true; } else return false;``
 
-   :param new_value: new value
+   :param ptr: address of the object to test and to modify
+   :param expected: value expected to be found in the object
+   :param desired: the value to store in the object if as expected
+   :returns: the result of the comparison, ``true`` if ``*ptr`` was equal to ``expected``, ``false`` otherwise

docs/source/API/core/atomics/atomic_exchange.rst

@@ -4,25 +4,33 @@
 .. role:: cppkokkos(code)
    :language: cppkokkos
 
-Header File: <Kokkos_Core.hpp>
+Defined in header ``<Kokkos_Atomic.hpp>`` which is included from ``<Kokkos_Core.hpp>``
 
 Usage
 -----
 
 .. code-block:: cpp
 
-   old_val = atomic_exchange(ptr_to_value, new_value);
+   auto old = atomic_exchange(&obj, desired);
 
-Atomically sets the value at the address given by ``ptr_to_value`` to ``new_value`` and returns the previously stored value at the address.
+Atomically replaces the value of ``obj`` with ``desired`` and returs the value before the call.
 
 Description
 -----------
 
-.. cppkokkos:function:: template<class T> T atomic_exchange(T* const ptr_to_value, const T new_value);
+.. cppkokkos:function:: template<class T> T atomic_exchange(T* ptr, std::type_identity_t<T> val);
 
-   Atomically executes ``old_value = *ptr_to_value; *ptr_to_value = new_value; return old_value;``,
-   where ``old_value`` is the value at address ``ptr_to_value`` before doing the exchange.
+   Atomically writes ``val`` into ``*ptr`` and returns the original value of ``*ptr``.
 
-   :param ptr_to_value: address of the value to be updated
+   ``{ auto old = *ptr; *ptr = val; return old; }``
 
-   :param new_value: new value
+   :param ptr: address of the object to modify
+   :param val: the value to store in the referenced object
+   :returns: the value held previously by the object pointed to by ``ptr``
+
+
+See also
+--------
+* `atomic_load <atomic_load.html>`_: atomically obtains the value of the referenced object
+* `atomic_store <atomic_store.html>`_: atomically replaces the value of the referenced object with a non-atomic argument
+* `atomic_compare_exchange <atomic_compare_exchange.html>`_: atomically compares the value of the referenced object with non-atomic argument and performs atomic exchange if equal or atomic load if not

docs/source/API/core/atomics/atomic_load.rst

@@ -13,16 +13,19 @@ Usage
 
     auto current = atomic_load(&obj);
 
-Atomically obtains ``obj``'s value.
+Atomically obtains the current value of ``obj``.
 
 Description
 -----------
 
 .. cppkokkos:function:: template<class T> T atomic_load(T* ptr);
 
-   Atomically reads the content of ``*ptr`` and returns it (``T val = *ptr; return val;``). 
+   Atomically reads the content of ``*ptr`` and returns it.
 
-   - ``ptr``: address of the object whose current value is to be returned.
+   ``{ T val = *ptr; return val; }``
+
+   :param ptr: address of the object whose current value is to be returned
+   :returns: the value that is held by the object pointed to by ``ptr``
 
 See also
 --------

docs/source/API/core/atomics/atomic_store.rst

@@ -13,18 +13,20 @@ Usage
 
     atomic_store(&obj, desired);
 
-Atomically replaces ``obj``'s value with ``desired``.
+Atomically replaces the current value of ``obj`` with ``desired``.
 
 Description
 -----------
 
 .. cppkokkos:function:: template<class T> void atomic_store(T* ptr, std::type_identity_t<T> val);
 
-   Atomically writes ``val`` into ``*ptr`` (``*ptr = val;``).
+   Atomically writes ``val`` into ``*ptr``.
 
-   - ``ptr``: address of the object whose value is to be replaced.
+   ``{ *ptr = val; }``
 
-   - ``val``: value to store in the referenced object.
+   :param ptr: address of the object whose value is to be replaced
+   :param val: the value to store in the referenced object
+   :returns: (nothing)
 
 
 See also