std::unique_lock

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Thread support library

Threads
thread (C++11)
hardware_destructive_interference_sizehardware_constructive_interference_size (C++17)(C++17)
this_thread namespace
get_id (C++11) yield (C++11)	sleep_for (C++11) sleep_until (C++11)
Mutual exclusion
mutex (C++11) recursive_mutex (C++11) shared_mutex (C++17)	timed_mutex (C++11) recursive_timed_mutex (C++11) shared_timed_mutex (C++14)
Generic lock management
lock_guard (C++11) scoped_lock (C++17) unique_lock (C++11) shared_lock (C++14) defer_lock_ttry_to_lock_tadopt_lock_t (C++11)(C++11)(C++11)	lock (C++11) try_lock (C++11) defer_locktry_to_lockadopt_lock (C++11)(C++11)(C++11) once_flag (C++11) call_once (C++11)
Condition variables
condition_variable (C++11)
condition_variable_any (C++11)
notify_all_at_thread_exit (C++11)
cv_status (C++11)
Futures
promise (C++11) future (C++11) shared_future (C++11) packaged_task (C++11) async (C++11)	launch (C++11) future_status (C++11) future_error (C++11) future_category (C++11) future_errc (C++11)

 

std::unique_lock

Member functions

unique_lock::unique_lock

unique_lock::~unique_lock

unique_lock::operator=

Locking

unique_lock::lock

unique_lock::try_lock

unique_lock::try_lock_for

unique_lock::try_lock_until

unique_lock::unlock

Modifiers

unique_lock::swap

unique_lock::release

Observers

unique_lock::mutex

unique_lock::owns_lock

unique_lock::operator bool

Non-member functions

std::swap

 

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

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

Non-member functions

std::swap(std::unique_lock) (C++11)

specialization of std::swap for unique_lock (function template)

Example

Run this code

#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

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