1.. _rw_mutex:
2
3rw_mutex
4=============
5
6.. note::
7   To enable this feature, define the ``TBB_PREVIEW_MUTEXES`` macro to 1.
8
9Description
10***********
11
12A ``rw_mutex`` is a class that models the `ReaderWriterMutex requirement <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/named_requirements/mutexes/rw_mutex.html>`_,
13using adaptive approach: the combination of spinlock and waiting on system primitives.
14The ``rw_mutex`` class satisfies all of the shared mutex requirements described in the [thread.sharedmutex.requirements] section of the ISO C++ standard.
15The ``rw_mutex`` class is unfair reader-writer lock with writer-preference.
16
17API
18***
19
20Header
21------
22
23.. code:: cpp
24
25    #include <oneapi/tbb/rw_mutex.h>
26
27Synopsis
28--------
29.. code:: cpp
30
31    namespace oneapi {
32        namespace tbb {
33            class rw_mutex {
34            public:
35                rw_mutex() noexcept;
36                ~rw_mutex();
37
38                rw_mutex(const rw_mutex&) = delete;
39                rw_mutex& operator=(const rw_mutex&) = delete;
40
41                class scoped_lock;
42
43                // exclusive ownership
44                void lock();
45                bool try_lock();
46                void unlock();
47
48                // shared ownership
49                void lock_shared();
50                bool try_lock_shared();
51                void unlock_shared();
52
53                static constexpr bool is_rw_mutex = true;
54                static constexpr bool is_recursive_mutex = false;
55                static constexpr bool is_fair_mutex = false;
56            };
57        }
58    }
59
60Member classes
61--------------
62
63.. namespace:: tbb::rw_mutex
64
65.. cpp:class:: scoped_lock
66
67    The corresponding scoped-lock class. See the `ReaderWriterMutex requirement <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/named_requirements/mutexes/rw_mutex.html>`_.
68
69Member functions
70----------------
71
72.. cpp:function:: rw_mutex()
73
74    Constructs unlocked ``rw_mutex``.
75
76--------------------------------------------------
77
78.. cpp:function:: ~rw_mutex()
79
80    Destroys unlocked ``rw_mutex``.
81
82--------------------------------------------------
83
84.. cpp:function:: void lock()
85
86    Acquires a lock. It uses adaptive logic for waiting: it blocks after particular time period of busy wait.
87
88--------------------------------------------------
89
90.. cpp:function:: bool try_lock()
91
92    Tries to acquire a lock (non-blocking) on write. Returns **true** if succeeded; **false** otherwise.
93
94--------------------------------------------------
95
96.. cpp:function:: void unlock()
97
98    Releases the write lock held by the current thread.
99
100--------------------------------------------------
101
102.. cpp:function:: void lock_shared()
103
104    Acquires a lock on read. It uses adaptive logic for waiting: it blocks after particular time period of busy wait.
105
106--------------------------------------------------
107
108.. cpp:function:: bool try_lock_shared()
109
110    Tries to acquire the lock (non-blocking) on read. Returns **true** if succeeded; **false** otherwise.
111
112--------------------------------------------------
113
114.. cpp:function:: void unlock_shared()
115
116    Releases the read lock held by the current thread.
117