std::mutex

From cppreference.com
< cpp‎ | thread
 
 
Concurrency support library
Threads
(C++11)
(C++20)
(C++20)
this_thread namespace
(C++11)
(C++11)
(C++11)
Atomic types
(C++11)
(C++20)
Initialization of atomic types
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
Free functions for atomic operations
Free functions for atomic flags
Memory ordering
Mutual exclusion
mutex
(C++11)
Generic lock management
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
Condition variables
(C++11)
Semaphores
Latches and barriers
(C++20)
(C++20)
Futures
(C++11)
(C++11)
(C++11)
(C++11)
 
std::mutex
 
Defined in header <mutex>
class mutex;
(since C++11)

The mutex class is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads.

mutex offers exclusive, non-recursive ownership semantics:

  • A calling thread owns a mutex from the time that it successfully calls either lock or try_lock until it calls unlock.
  • When a thread owns a mutex, all other threads will block (for calls to lock) or receive a false return value (for try_lock) if they attempt to claim ownership of the mutex.
  • A calling thread must not own the mutex prior to calling lock or try_lock.

The behavior of a program is undefined if a mutex is destroyed while still owned by any threads, or a thread terminates while owning a mutex. The mutex class satisfies all requirements of Mutex and StandardLayoutType.

std::mutex is neither copyable nor movable.

Member types

Member type Definition
native_handle_type(not always present) implementation-defined

Member functions

constructs the mutex
(public member function)
destroys the mutex
(public member function)
operator=
[deleted]
not copy-assignable
(public member function)
Locking
locks the mutex, blocks if the mutex is not available
(public member function)
tries to lock the mutex, returns if the mutex is not available
(public member function)
unlocks the mutex
(public member function)
Native handle
returns the underlying implementation-defined native handle object
(public member function)

Notes

std::mutex is usually not accessed directly: std::unique_lock, std::lock_guard, or std::scoped_lock (since C++17) manage locking in a more exception-safe manner.

Example

This example shows how a mutex can be used to protect an std::map shared between two threads.

#include <iostream>
#include <map>
#include <string>
#include <chrono>
#include <thread>
#include <mutex>
 
std::map<std::string, std::string> g_pages;
std::mutex g_pages_mutex;
 
void save_page(const std::string &url)
{
    // simulate a long page fetch
    std::this_thread::sleep_for(std::chrono::seconds(2));
    std::string result = "fake content";
 
    std::lock_guard<std::mutex> guard(g_pages_mutex);
    g_pages[url] = result;
}
 
int main() 
{
    std::thread t1(save_page, "http://foo");
    std::thread t2(save_page, "http://bar");
    t1.join();
    t2.join();
 
    // safe to access g_pages without lock now, as the threads are joined
    for (const auto &pair : g_pages) {
        std::cout << pair.first << " => " << pair.second << '\n';
    }
}

Output:

http://bar => fake content
http://foo => fake content

See also

provides mutual exclusion facility which can be locked recursively by the same thread
(class)
implements a strictly scope-based mutex ownership wrapper
(class template)
implements movable mutex ownership wrapper
(class template)
deadlock-avoiding RAII wrapper for multiple mutexes
(class template)
provides a condition variable associated with a std::unique_lock
(class)