Difference between revisions of "cpp/thread/shared mutex"

Latest revision as of 05:06, 13 June 2023

Defined in header `<shared_mutex>`
class shared_mutex;		(since C++17)

The shared_mutex class is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads. In contrast to other mutex types which facilitate exclusive access, a shared_mutex has two levels of access:

shared - several threads can share ownership of the same mutex.

exclusive - only one thread can own the mutex.

If one thread has acquired the exclusive lock (through lock, try_lock), no other threads can acquire the lock (including the shared).

If one thread has acquired the shared lock (through lock_shared, try_lock_shared), no other thread can acquire the exclusive lock, but can acquire the shared lock.

Only when the exclusive lock has not been acquired by any thread, the shared lock can be acquired by multiple threads.

Within one thread, only one lock (shared or exclusive) can be acquired at the same time.

Shared mutexes are especially useful when shared data can be safely read by any number of threads simultaneously, but a thread may only write the same data when no other thread is reading or writing at the same time.

The shared_mutex class satisfies all requirements of SharedMutex and StandardLayoutType.

(constructor)	constructs the mutex (public member function) [edit]
(destructor)	destroys the mutex (public member function) [edit]
operator= [deleted]	not copy-assignable (public member function) [edit]
Exclusive locking
lock	locks the mutex, blocks if the mutex is not available (public member function) [edit]
try_lock	tries to lock the mutex, returns if the mutex is not available (public member function) [edit]
unlock	unlocks the mutex (public member function) [edit]
Shared locking
lock_shared	locks the mutex for shared ownership, blocks if the mutex is not available (public member function) [edit]
try_lock_shared	tries to lock the mutex for shared ownership, returns if the mutex is not available (public member function) [edit]
unlock_shared	unlocks the mutex (shared ownership) (public member function) [edit]
Native handle
native_handle	returns the underlying implementation-defined native handle object (public member function) [edit]

[edit] Example

The output below was generated on a single-core machine. When thread1 starts, it enters the loop for the first time and calls increment() followed by get(). However, before it can print the returned value to std::cout, the scheduler puts thread1 to sleep and wakes up thread2, which obviously has time enough to run all three loop iterations at once. Back to thread1, still in the first loop iteration, it finally prints its local copy of the counter's value, which is 1, to std::cout and then runs the remaining two loop iterations. On a multi-core machine, none of the threads is put to sleep and the output is more likely to be in ascending order.

Run this code

#include <iostream>
#include <mutex>
#include <shared_mutex>
#include <syncstream>
#include <thread>
 
class ThreadSafeCounter
{
public:
    ThreadSafeCounter() = default;
 
    // Multiple threads/readers can read the counter's value at the same time.
    unsigned int get() const
    {
        std::shared_lock lock(mutex_);
        return value_;
    }
 
    // Only one thread/writer can increment/write the counter's value.
    void increment()
    {
        std::unique_lock lock(mutex_);
        ++value_;
    }
 
    // Only one thread/writer can reset/write the counter's value.
    void reset()
    {
        std::unique_lock lock(mutex_);
        value_ = 0;
    }
 
private:
    mutable std::shared_mutex mutex_;
    unsigned int value_{};
};
 
int main()
{
    ThreadSafeCounter counter;
 
    auto increment_and_print = [&counter]()
    {
        for (int i{}; i != 3; ++i)
        {
            counter.increment();
            std::osyncstream(std::cout)
                << std::this_thread::get_id() << ' ' << counter.get() << '\n';
        }
    };
 
    std::thread thread1(increment_and_print);
    std::thread thread2(increment_and_print);
 
    thread1.join();
    thread2.join();
}

Possible output:

123084176803584 2
123084176803584 3
123084176803584 4
123084185655040 1
123084185655040 5
123084185655040 6

[edit] See also

shared_timed_mutex (C++14)	provides shared mutual exclusion facility and implements locking with a timeout (class) [edit]
shared_lock (C++14)	implements movable shared mutex ownership wrapper (class template) [edit]
unique_lock (C++11)	implements movable mutex ownership wrapper (class template) [edit]

@@ Line 1: / Line 1: @@
 {{cpp/title|shared_mutex}}
 {{cpp/thread/shared_mutex/navbar}}
-{{ddcl | header=shared_mutex | since=c++17 | 1=
+{{ddcl|header=shared_mutex|since=c++17|1=
 class shared_mutex;
 }}
@@ Line 25: / Line 25: @@
 ===Member types===
 {{dsc begin}}
-{{dsc hitem | Member type | Definition}}
+{{dsc hitem|Member type|Definition}}
-{{dsc inc | cpp/thread/dsc native_handle_type | shared_mutex}}
+{{dsc inc|cpp/thread/dsc native_handle_type|shared_mutex}}
 {{dsc end}}
 ===Member functions===
 {{dsc begin}}
-{{dsc inc | cpp/thread/mutex/dsc constructor | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc constructor|shared_mutex}}
-{{dsc inc | cpp/thread/mutex/dsc destructor | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc destructor|shared_mutex}}
-{{dsc inc | cpp/thread/mutex/dsc operator{{=}}}}
+{{dsc inc|cpp/thread/mutex/dsc operator{{=}}}}
-{{dsc h2 | Exclusive locking}}
+{{dsc h2|Exclusive locking}}
-{{dsc inc | cpp/thread/mutex/dsc lock | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc lock|shared_mutex}}
-{{dsc inc | cpp/thread/mutex/dsc try_lock | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc try_lock|shared_mutex}}
-{{dsc inc | cpp/thread/mutex/dsc unlock | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc unlock|shared_mutex}}
-{{dsc h2 | Shared locking}}
+{{dsc h2|Shared locking}}
-{{dsc inc | cpp/thread/mutex/dsc lock_shared | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc lock_shared|shared_mutex}}
-{{dsc inc | cpp/thread/mutex/dsc try_lock_shared | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc try_lock_shared|shared_mutex}}
-{{dsc inc | cpp/thread/mutex/dsc unlock_shared | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc unlock_shared|shared_mutex}}
-{{dsc h2 | Native handle}}
+{{dsc h2|Native handle}}
-{{dsc inc | cpp/thread/mutex/dsc native_handle | shared_mutex}}
+{{dsc inc|cpp/thread/mutex/dsc native_handle|shared_mutex}}
 {{dsc end}}
 ===Example===
 {{example
- | p=true
+|The output below was generated on a single-core machine. When {{tt|thread1}} starts, it enters the loop for the first time and calls {{tt|increment()}} followed by {{tt|get()}}. However, before it can print the returned value to {{c/core|std::cout}}, the scheduler puts {{tt|thread1}} to sleep and wakes up {{tt|thread2}}, which obviously has time enough to run all three loop iterations at once. Back to {{tt|thread1}}, still in the first loop iteration, it finally prints its local copy of the counter's value, which is {{c|1}}, to {{tt|std::cout}} and then runs the remaining two loop iterations. On a multi-core machine, none of the threads is put to sleep and the output is more likely to be in ascending order.
- | code=
+|code=
 #include <iostream>
 #include <mutex>
 #include <shared_mutex>
+#include <syncstream>
 #include <thread>
-class ThreadSafeCounter {
+class ThreadSafeCounter
- public:
+{
-  ThreadSafeCounter() = default;
+public:
+    ThreadSafeCounter() = default;
-  // Multiple threads/readers can read the counter's value at the same time.
+    // Multiple threads/readers can read the counter's value at the same time.
-  unsigned int get() const {
+    unsigned int get() const
-     std::shared_lock lock(mutex_);
+     {
-    return value_;
+        std::shared_lock lock(mutex_);
-  }
+        return value_;
+    }
-  // Only one thread/writer can increment/write the counter's value.
+    // Only one thread/writer can increment/write the counter's value.
-  void increment() {
+    void increment()
-     std::unique_lock lock(mutex_);
+     {
-    ++value_;
+        std::unique_lock lock(mutex_);
-  }
+        ++value_;
+    }
-  // Only one thread/writer can reset/write the counter's value.
+    // Only one thread/writer can reset/write the counter's value.
-  void reset() {
+    void reset()
-     std::unique_lock lock(mutex_);
+     {
-    value_ = 0;
+        std::unique_lock lock(mutex_);
-  }
+        value_ = 0;
+    }
- private:
+private:
-  mutable std::shared_mutex mutex_;
+    mutable std::shared_mutex mutex_;
-  unsigned int value_ = 0;
+    unsigned int value_{};
 };
-int main() {
+int main()
-  ThreadSafeCounter counter;
+{
+    ThreadSafeCounter counter;
-  auto increment_and_print = [&counter]() {
+    auto increment_and_print = [&counter]()
-     for (int i = 0; i < 3; i++) {
+     {
-      counter.increment();
+        for (int i{}; i != 3; ++i)
-      std::cout << std::this_thread::get_id() << ' ' << counter.get() << '\n';
+        {
+            counter.increment();
+            std::osyncstream(std::cout)
+                << std::this_thread::get_id() << ' ' << counter.get() << '\n';
+        }
+    };
-      // Note: Writing to std::cout actually needs to be synchronized as well
+    std::thread thread1(increment_and_print);
-      // by another std::mutex. This has been omitted to keep the example small.
+    std::thread thread2(increment_and_print);
-    }
-  };
-  std::thread thread1(increment_and_print);
+    thread1.join();
-  std::thread thread2(increment_and_print);
+    thread2.join();
-  thread1.join();
-  thread2.join();
 }
+|p=true
-// Explanation: The output below was generated on a single-core machine. When
+|output=
-// thread1 starts, it enters the loop for the first time and calls increment()
-// followed by get(). However, before it can print the returned value to
-// std::cout, the scheduler puts thread1 to sleep and wakes up thread2, which
-// obviously has time enough to run all three loop iterations at once. Back to
-// thread1, still in the first loop iteration, it finally prints its local copy
-// of the counter's value, which is 1, to std::cout and then runs the remaining
-// two loop iterations. On a multi-core machine, none of the threads is put to
-// sleep and the output is more likely to be in ascending order.
- | output=
 123084176803584 2
 123084176803584 3
@@ Line 126: / Line 122: @@
 ===See also===
 {{dsc begin}}
-{{dsc inc | cpp/thread/dsc shared_timed_mutex}}
+{{dsc inc|cpp/thread/dsc shared_timed_mutex}}
-{{dsc inc | cpp/thread/dsc shared_lock}}
+{{dsc inc|cpp/thread/dsc shared_lock}}
-{{dsc inc | cpp/thread/dsc unique_lock}}
+{{dsc inc|cpp/thread/dsc unique_lock}}
 {{dsc end}}
 {{langlinks|es|ja|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Member functions
shared_mutex::shared_mutex
shared_mutex::~shared_mutex
Exclusive locking
shared_mutex::lock
shared_mutex::try_lock
shared_mutex::unlock
Shared locking
shared_mutex::lock_shared
shared_mutex::try_lock_shared
shared_mutex::unlock_shared
Native handle
shared_mutex::native_handle

Member type	Definition
`native_handle_type` (optional*)	implementation-defined[edit]

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/thread/shared mutex"

Latest revision as of 05:06, 13 June 2023

Contents

[edit] Member types

[edit] Member functions

Exclusive locking

Shared locking

Native handle

[edit] Example

[edit] See also

Navigation

Toolbox