Namespaces
Variants
Actions

std::unique_lock

From cppreference.com
< cpp‎ | thread
 
 
Concurrency support library
(C++11)
(C++20)
(C++11)
(C++11)
(C++11)
(C++11)
Cooperative cancellation
(C++20)
(C++20)
Mutual exclusion
(C++11)
(C++17)
Generic lock management
(C++11)
(C++11)
(C++17)
unique_lock
(C++11)
(C++14)
(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)
(C++11)
(C++11)
Safe reclamation
(C++26)
(C++26)
(C++26)
(C++26)
Hazard pointers
(C++11)
(C++20)
(C++11)
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
(C++11)
(C++11)(deprecated in C++26)
 
 
Defined in header <mutex>
template< class Mutex >
class unique_lock;
(since C++11)

The class unique_lock is a general-purpose mutex ownership wrapper allowing deferred locking, time-constrained attempts at locking, recursive locking, transfer of lock ownership, and use with condition variables.

The class unique_lock is movable, but not copyable -- it meets the requirements of MoveConstructible and MoveAssignable but not of CopyConstructible or CopyAssignable.

The class unique_lock meets the BasicLockable requirements. If Mutex meets the Lockable requirements, unique_lock also meets the Lockable requirements (ex.: can be used in std::lock ); if Mutex meets the TimedLockable requirements, unique_lock also meets the TimedLockable requirements.

[edit] Template parameters

Mutex - the type of the mutex to lock. The type must meet the BasicLockable requirements

[edit] Nested types

Type Definition
mutex_type Mutex

[edit] Member functions

constructs a unique_lock, optionally locking (i.e., taking ownership of) the supplied mutex
(public member function) [edit]
unlocks (i.e., releases ownership of) the associated mutex, if owned
(public member function) [edit]
unlocks (i.e., releases ownership of) the mutex, if owned, and acquires ownership of another
(public member function) [edit]
Locking
locks (i.e., takes ownership of) the associated mutex
(public member function) [edit]
tries to lock (i.e., takes ownership of) the associated mutex without blocking
(public member function) [edit]
attempts to lock (i.e., takes ownership of) the associated TimedLockable mutex, returns if the mutex has been unavailable for the specified time duration
(public member function) [edit]
tries to lock (i.e., takes ownership of) the associated TimedLockable mutex, returns if the mutex has been unavailable until specified time point has been reached
(public member function) [edit]
unlocks (i.e., releases ownership of) the associated mutex
(public member function) [edit]
Modifiers
swaps state with another std::unique_lock
(public member function) [edit]
disassociates the associated mutex without unlocking (i.e., releasing ownership of) it
(public member function) [edit]
Observers
returns a pointer to the associated mutex
(public member function) [edit]
tests whether the lock owns (i.e., has locked) its associated mutex
(public member function) [edit]
tests whether the lock owns (i.e., has locked) its associated mutex
(public member function) [edit]

[edit] Non-member functions

specializes the std::swap algorithm
(function template) [edit]

[edit] Notes

A common beginner error is to "forget" to give a unique_lock variable a name, e.g. std::unique_lock(mtx); (which default constructs a unique_lock variable named mtx) or std::unique_lock{mtx}; (which constructs a prvalue object that is immediately destroyed), thereby not actually constructing a lock that holds a mutex for the rest of the scope.

[edit] Example

Run this code
#include <iostream>
#include <mutex>
#include <thread>
 
struct Box
{
 explicit Box(int num) : num_things{num} {}
 
 int num_things;
 std::mutex m;
};
 
void transfer(Box& from, Box& to, int num)
{
 // don't actually take the locks yet
 std::unique_lock lock1{from.m, std::defer_lock };
 std::unique_lock lock2{to.m, std::defer_lock };
 
 // lock both unique_locks without deadlock
 std::lock (lock1, lock2);
 
 from.num_things -= num;
 to.num_things += num;
 
 // "from.m" and "to.m" mutexes unlocked in unique_lock dtors
}
 
int main()
{
 Box acc1{100};
 Box acc2{50};
 
 std::thread t1{transfer, std::ref (acc1), std::ref (acc2), 10};
 std::thread t2{transfer, std::ref (acc2), std::ref (acc1), 5};
 
 t1.join();
 t2.join();
 
 std::cout << "acc1: " << acc1.num_things << "\n"
 "acc2: " << acc2.num_things << '\n';
}

Output:

acc1: 95
acc2: 55

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 2981 C++17 redundant deduction guide from unique_lock<Mutex> was provided removed

[edit] See also

(C++11)
locks specified mutexes, blocks if any are unavailable
(function template) [edit]
(C++11)
implements a strictly scope-based mutex ownership wrapper
(class template) [edit]
(C++17)
deadlock-avoiding RAII wrapper for multiple mutexes
(class template) [edit]
(C++11)
provides basic mutual exclusion facility
(class) [edit]

AltStyle によって変換されたページ (->オリジナル) /