[oneTBB] Add adaptive mutexes

source/elements/oneTBB/source/mutual_exclusion.rst

@@ -16,6 +16,8 @@ Mutex Classes
 .. toctree::
     :titlesonly:
 
+    mutual_exclusion/mutex_cls.rst
+    mutual_exclusion/rw_mutex_cls.rst
     mutual_exclusion/spin_mutex_cls.rst
     mutual_exclusion/spin_rw_mutex_cls.rst
     mutual_exclusion/speculative_spin_mutex_cls.rst

source/elements/oneTBB/source/mutual_exclusion/mutex_cls.rst

@@ -0,0 +1,80 @@
+.. SPDX-FileCopyrightText: 2020-2021 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+=====
+mutex
+=====
+**[mutex.mutex]**
+
+A ``mutex`` is a class that models :doc:`Mutex requirement <../named_requirements/mutexes/mutex>`
+using an adaptive approach, it guarantees: that the thread that can't acquire the lock spins before blocking.
+The ``mutex`` class satisfies all of the mutex requirements described in the [thread.mutex.requirements] section of the ISO C++ standard.
+The ``mutex`` class is not fair or recursive.
+
+.. code:: cpp
+
+    // Defined in header <oneapi/tbb/mutex.h>
+
+    namespace oneapi {
+        namespace tbb {
+            class mutex {
+            public:
+                mutex() noexcept;
+                ~mutex();
+
+                mutex(const mutex&) = delete;
+                mutex& operator=(const mutex&) = delete;
+
+                class scoped_lock;
+
+                void lock();
+                bool try_lock();
+                void unlock();
+
+                static constexpr bool is_rw_mutex = false;
+                static constexpr bool is_recursive_mutex = false;
+                static constexpr bool is_fair_mutex = false;
+            };
+        }
+    }
+
+Member classes
+--------------
+
+.. namespace:: oneapi::tbb::mutex
+
+.. cpp:class:: scoped_lock
+
+    The corresponding ``scoped_lock`` class. See :doc:`Mutex requirement <../named_requirements/mutexes/mutex>`.
+
+Member functions
+----------------
+
+.. cpp:function:: mutex()
+
+    Constructs a ``mutex`` with the unlocked state.
+
+--------------------------------------------------
+
+.. cpp:function:: ~mutex()
+
+    Destroys an unlocked ``mutex``.
+
+--------------------------------------------------
+
+.. cpp:function:: void lock()
+
+    Acquires a lock. It uses adaptive logic for waiting, thus it is blocked after a certain time of busy waiting.
+
+--------------------------------------------------
+
+.. cpp:function:: bool try_lock()
+
+    Tries to acquire a lock (non-blocking). Returns **true** if succeeded; **false** otherwise.
+
+--------------------------------------------------
+
+.. cpp:function:: void unlock()
+
+    Releases the lock held by a current thread.

source/elements/oneTBB/source/mutual_exclusion/rw_mutex_cls.rst

@@ -0,0 +1,104 @@
+.. SPDX-FileCopyrightText: 2020-2021 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+=============
+rw_mutex
+=============
+**[mutex.rw_mutex]**
+
+A ``rw_mutex`` is a class that models :doc:`ReaderWriterMutex requirement <../named_requirements/mutexes/rw_mutex>`
+using an adaptive approach, it guarantees: that the thread that can't acquire the lock spins before blocking.
+The ``rw_mutex`` class satisfies all of the shared mutex requirements described in the [thread.sharedmutex.requirements] section of the ISO C++ standard.
+The ``rw_mutex`` class is an unfair reader-writer lock with a writer preference.
+
+.. code:: cpp
+
+    // Defined in header <oneapi/tbb/rw_mutex.h>
+
+    namespace oneapi {
+        namespace tbb {
+            class rw_mutex {
+            public:
+                rw_mutex() noexcept;
+                ~rw_mutex();
+
+                rw_mutex(const rw_mutex&) = delete;
+                rw_mutex& operator=(const rw_mutex&) = delete;
+
+                class scoped_lock;
+
+                // exclusive ownership
+                void lock();
+                bool try_lock();
+                void unlock();
+
+                // shared ownership
+                void lock_shared();
+                bool try_lock_shared();
+                void unlock_shared();
+
+                static constexpr bool is_rw_mutex = true;
+                static constexpr bool is_recursive_mutex = false;
+                static constexpr bool is_fair_mutex = false;
+            };
+        }
+    }
+
+Member classes
+--------------
+
+.. namespace:: oneapi::tbb::rw_mutex
+
+.. cpp:class:: scoped_lock
+
+    The corresponding scoped-lock class. See :doc:`ReaderWriterMutex requirement <../named_requirements/mutexes/rw_mutex>`.
+
+Member functions
+----------------
+
+.. cpp:function:: rw_mutex()
+
+    Constructs an unlocked ``rw_mutex``.
+
+--------------------------------------------------
+
+.. cpp:function:: ~rw_mutex()
+
+    Destroys an unlocked ``rw_mutex``.
+
+--------------------------------------------------
+
+.. cpp:function:: void lock()
+
+    Acquires a lock. It uses an adaptive logic for waiting, thus it is blocked after a certain time of busy waiting.
+
+--------------------------------------------------
+
+.. cpp:function:: bool try_lock()
+
+    Tries to acquire a lock (non-blocking) on write. Returns **true** if succeeded; **false** otherwise.
+
+--------------------------------------------------
+
+.. cpp:function:: void unlock()
+
+    Releases the write lock held by the current thread.
+
+--------------------------------------------------
+
+.. cpp:function:: void lock_shared()
+
+    Acquires a lock on read. It uses an adaptive logic for waiting, thus it is blocked after a certain time of busy waiting.
+
+--------------------------------------------------
+
+.. cpp:function:: bool try_lock_shared()
+
+    Tries to acquire the lock (non-blocking) on read. Returns **true** if succeeded; **false** otherwise.
+
+--------------------------------------------------
+
+.. cpp:function:: void unlock_shared()
+
+    Releases the read lock held by the current thread.

source/elements/oneTBB/source/named_requirements/mutexes/mutex.rst

@@ -106,6 +106,8 @@ The following table summarizes the library classes that model the ``Mutex`` requ
    ============================= ============ =============
    .                             **Fair**     **Reentrant**
    ============================= ============ =============
+   ``mutex``                     No           No
+   ----------------------------- ------------ -------------
    ``spin_mutex``                No           No
    ----------------------------- ------------ -------------
    ``speculative_spin_mutex``    No           No
@@ -123,6 +125,7 @@ See the *oneAPI Threading Building Blocks Developer Guide* for description of th
 
 See also:
 
+* :doc:`mutex <../../mutual_exclusion/mutex_cls>`
 * :doc:`spin_mutex <../../mutual_exclusion/spin_mutex_cls>`
 * :doc:`speculative_spin_mutex <../../mutual_exclusion/speculative_spin_mutex_cls>`
 * :doc:`queuing_mutex <../../mutual_exclusion/queuing_mutex_cls>`

source/elements/oneTBB/source/named_requirements/mutexes/rw_mutex.rst

@@ -100,6 +100,8 @@ The following table summarizes the library classes that model the `ReaderWriterM
     ============================= ============ =============
     .                             **Fair**     **Reentrant**
     ============================= ============ =============
+    ``rw_mutex``                  No           No
+    ----------------------------- ------------ -------------
     ``spin_rw_mutex``             No           No
     ----------------------------- ------------ -------------
     ``speculative_spin_rw_mutex`` No           No
@@ -124,6 +126,7 @@ The following table summarizes the library classes that model the `ReaderWriterM
 
 See also:
 
+* :doc:`rw_mutex <../../mutual_exclusion/rw_mutex_cls>`
 * :doc:`spin_rw_mutex <../../mutual_exclusion/spin_rw_mutex_cls>`
 * :doc:`speculative_spin_rw_mutex <../../mutual_exclusion/speculative_spin_rw_mutex_cls>`
 * :doc:`queuing_rw_mutex <../../mutual_exclusion/queuing_rw_mutex_cls>`