std::unique_lock

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Concurrency support library

Threads thread (C++11) jthread (C++20) stop_token (C++20) stop_source (C++20) stop_callback (C++20) 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) Atomic types atomic (C++11) atomic_ref (C++20) atomic_flag (C++11) Initialization of atomic types atomic_init (C++11)(deprecated in C++20) ATOMIC_VAR_INIT (C++11)(deprecated in C++20) ATOMIC_FLAG_INIT (C++11) Free functions for atomic operations atomic_storeatomic_store_explicit (C++11)(C++11) atomic_loadatomic_load_explicit (C++11)(C++11) atomic_exchangeatomic_exchange_explicit (C++11)(C++11) atomic_compare_exchange_weakatomic_compare_exchange_weak_explicitatomic_compare_exchange_strongatomic_compare_exchange_strong_explicit (C++11)(C++11)(C++11)(C++11) atomic_fetch_addatomic_fetch_add_explicit (C++11)(C++11) atomic_fetch_subatomic_fetch_sub_explicit (C++11)(C++11) atomic_fetch_andatomic_fetch_and_explicit (C++11)(C++11) atomic_fetch_oratomic_fetch_or_explicit (C++11)(C++11) atomic_fetch_xoratomic_fetch_xor_explicit (C++11)(C++11) atomic_is_lock_free (C++11) atomic_waitatomic_wait_explicit (C++20)(C++20) atomic_notify_one (C++20) atomic_notify_all (C++20)

Free functions for atomic flags atomic_flag_test_and_setatomic_flag_test_and_set_explicit (C++11)(C++11) atomic_flag_clearatomic_flag_clear_explicit (C++11)(C++11) atomic_flag_testatomic_flag_test_explicit (C++20)(C++20) atomic_flag_waitatomic_flag_wait_explicit (C++20)(C++20) atomic_flag_notify_one (C++20) atomic_flag_notify_all (C++20) Memory ordering memory_order (C++11) kill_dependency (C++11) atomic_thread_fence (C++11) atomic_signal_fence (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) Semaphores counting_semaphorebinary_semaphore (C++20)(C++20) Latches and barriers latch (C++20) barrier (C++20) 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 (i.e., taking ownership of) the supplied mutex (public member function)
(destructor)	unlocks (i.e., releases ownership of) the associated mutex, if owned (public member function)
operator=	unlocks (i.e., releases ownership of) the mutex, if owned, and acquires ownership of another (public member function)
Locking
lock	locks (i.e., takes ownership of) the associated mutex (public member function)
try_lock	tries to lock (i.e., takes ownership of) the associated mutex without blocking (public member function)
try_lock_for	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)
try_lock_until	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)
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)
release	disassociates the associated mutex without unlocking (i.e., releasing 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) (C++11)

specialization of std::swap for unique_lock (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 unique_lock<Mutex> was provided	removed

See also

lock (C++11)	locks specified mutexes, blocks if any are unavailable (function template)
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)
mutex (C++11)	provides basic mutual exclusion facility (class)