std::unique_lock (3) - Linux Manuals

std::unique_lock: std::unique_lock

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

Locking

               locks the associated mutex
lock (public member function)
               tries to lock the associated mutex, returns if the mutex is not available
try_lock (public member function)
               attempts to lock the associated TimedLockable mutex, returns if the mutex has been unavailable for the specified time duration
try_lock_for (public member function)
               tries to lock the associated TimedLockable mutex, returns if the mutex has been unavailable until specified time point has been reached
try_lock_until (public member function)
               unlocks the associated mutex
unlock (public member function)

Modifiers

               swaps state with another std::unique_lock
swap (public member function)
               disassociates the associated mutex without unlocking it
release (public member function)

Observers

               returns a pointer to the associated mutex
mutex (public member function)
               tests whether the lock owns its associated mutex
owns_lock (public member function)
               tests whether the lock owns its associated mutex
operator_bool (public member function)

Non-member functions

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

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