std::unique_lock

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.

Template parameters

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

Member types

Type Definition
mutex_type Mutex

Member functions

constructs a unique_lock, optionally locking the supplied mutex
(public member function)
unlocks the associated mutex, if owned
(public member function)
unlocks the mutex, if owned, and acquires ownership of another
(public member function)
Locking
locks the associated mutex
(public member function)
tries to lock the associated mutex, returns if the mutex is not available
(public member function)
attempts to lock the associated TimedLockable mutex, returns if the mutex has been unavailable for the specified time duration
(public member function)
tries to lock the associated TimedLockable mutex, returns if the mutex has been unavailable until specified time point has been reached
(public member function)
unlocks the associated mutex
(public member function)
Modifiers
swaps state with another std::unique_lock
(public member function)
disassociates the associated mutex without unlocking it
(public member function)
Observers
returns a pointer to the associated mutex
(public member function)
tests whether the lock owns its associated mutex
(public member function)
tests whether the lock owns its associated mutex
(public member function)

Non-member functions

(C++11)
specialization of std::swap for unique_lock
(function template)

Example

#include <mutex>
#include <thread>
#include <chrono>
 
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<std::mutex> lock1(from.m, std::defer_lock);
    std::unique_lock<std::mutex> 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();
}

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

See also

(C++11)
implements a strictly scope-based mutex ownership wrapper
(class template)
(C++17)
deadlock-avoiding RAII wrapper for multiple mutexes
(class template)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/thread/unique_lock