std::unique_lock

From cppreference.com
< cpp‎ | thread
 
 
Concurrency support library
Threads
(C++11)
(C++20)
(C++20)
this_thread namespace
(C++11)
(C++11)
(C++11)
Atomic types
(C++11)
(C++20)
Initialization of atomic types
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
Free functions for atomic operations
Free functions for atomic flags
Memory ordering
Mutual exclusion
(C++11)
Generic lock management
(C++11)
unique_lock
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(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)
 
 
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 (i.e., taking ownership of) the supplied mutex
(public member function)
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 acquires ownership of another
(public member function)
Locking
locks (i.e., takes ownership of) the associated mutex
(public member function)
tries to lock (i.e., takes ownership of) the associated mutex without blocking
(public member function)
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)
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)
unlocks (i.e., releases ownership of) the associated mutex
(public member function)
Modifiers
swaps state with another std::unique_lock
(public member function)
disassociates the associated mutex without unlocking (i.e., releasing ownership of) it
(public member function)
Observers
returns a pointer to the associated mutex
(public member function)
tests whether the lock owns (i.e., has locked) its associated mutex
(public member function)
tests whether the lock owns (i.e., has locked) its associated mutex
(public member function)

Non-member functions

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

Example

#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

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