NAME¶

std::unique_lock - std::unique_lock

Synopsis¶

Defined in header <mutex>
template< class Mutex > (since C++11)
class unique_lock;

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 (i.e., taking ownership
constructor of) the supplied mutex
(public member function)
destructor unlocks (i.e., releases ownership of) the associated mutex, if owned
(public member function)
unlocks (i.e., releases ownership of) the mutex, if owned, and
operator= acquires ownership of another
(public member function)

Locking¶

lock locks (i.e., takes ownership of) the associated mutex
(public member function)
tries to lock (i.e., takes ownership of) the associated mutex without
try_lock blocking
(public member function)
attempts to lock (i.e., takes ownership of) the associated
try_lock_for TimedLockable mutex, returns if the mutex has been unavailable for
the specified time duration
(public member function)
tries to lock (i.e., takes ownership of) the associated TimedLockable
try_lock_until mutex, returns if the mutex has been unavailable until specified time
point has been reached
(public member function)
unlock unlocks (i.e., releases ownership of) the associated mutex
(public member function)

Modifiers¶

swap swaps state with another std::unique_lock
(public member function)
disassociates the associated mutex without unlocking (i.e., releasing
release ownership of) it
(public member function)

Observers¶

mutex returns a pointer to the associated mutex
(public member function)
owns_lock tests whether the lock owns (i.e., has locked) its associated mutex
(public member function)
operator bool tests whether the lock owns (i.e., has locked) its associated mutex
(public member function)

Non-member functions¶

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

Example¶

// Run this code

#include <mutex>
#include <thread>
#include <iostream>

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

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 removed
unique_lock<Mutex> was provided

See also¶

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