std::unique_lock(3)

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
   Nested 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 <iostream>
 #include <mutex>
 #include <thread>
 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)