diff --git a/source/elements/oneTBB/source/mutual_exclusion.rst b/source/elements/oneTBB/source/mutual_exclusion.rst index 11c0775943..e908decd91 100644 --- a/source/elements/oneTBB/source/mutual_exclusion.rst +++ b/source/elements/oneTBB/source/mutual_exclusion.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 @@ -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 diff --git a/source/elements/oneTBB/source/mutual_exclusion/mutex_cls.rst b/source/elements/oneTBB/source/mutual_exclusion/mutex_cls.rst new file mode 100644 index 0000000000..7f735ab97f --- /dev/null +++ b/source/elements/oneTBB/source/mutual_exclusion/mutex_cls.rst @@ -0,0 +1,80 @@ +.. SPDX-FileCopyrightText: 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 cannot 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 + + 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 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). Returns **true** if succeeded; **false** otherwise. + +-------------------------------------------------- + +.. cpp:function:: void unlock() + + Releases the lock held by a current thread. diff --git a/source/elements/oneTBB/source/mutual_exclusion/rw_mutex_cls.rst b/source/elements/oneTBB/source/mutual_exclusion/rw_mutex_cls.rst new file mode 100644 index 0000000000..2883d68a82 --- /dev/null +++ b/source/elements/oneTBB/source/mutual_exclusion/rw_mutex_cls.rst @@ -0,0 +1,104 @@ +.. SPDX-FileCopyrightText: 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 cannot 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 + + 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. diff --git a/source/elements/oneTBB/source/named_requirements/mutexes/mutex.rst b/source/elements/oneTBB/source/named_requirements/mutexes/mutex.rst index 36fe775bc0..4fce61c2fa 100644 --- a/source/elements/oneTBB/source/named_requirements/mutexes/mutex.rst +++ b/source/elements/oneTBB/source/named_requirements/mutexes/mutex.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 @@ -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>` diff --git a/source/elements/oneTBB/source/named_requirements/mutexes/rw_mutex.rst b/source/elements/oneTBB/source/named_requirements/mutexes/rw_mutex.rst index 5fba8765b6..e9109ead06 100644 --- a/source/elements/oneTBB/source/named_requirements/mutexes/rw_mutex.rst +++ b/source/elements/oneTBB/source/named_requirements/mutexes/rw_mutex.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 @@ -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>`