home | help 
std::unique_lock(3)	       C++ Standard Libary	     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 al-
     lowing deferred
	locking, time-constrained attempts at locking, recursive locking, trans-
     fer of lock
	ownership, and use with condition variables.

	The class unique_lock is movable, but not copyable -- it meets	the  re-
     quirements 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 BasicLock-
     able
		requirements

	Nested types

	Type	   Definition
	mutex_type Mutex

Member functions
		       constructs  a unique_lock, optionally locking (i.e., tak-
     ing ownership
	constructor    of) the supplied mutex
		       (public member function)
	destructor     unlocks (i.e., releases ownership of) the associated  mu-
     tex, 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 associ-
     ated
	try_lock_for   TimedLockable mutex, returns if the mutex  has  been  un-
     available 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 mu-
     tex
		       (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 asso-
     ciated mutex
		       (public member function)
	operator bool  tests whether the lock owns (i.e., has locked) its  asso-
     ciated 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;

	  // afrom.ma and ato.ma 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 retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to		 Behavior as published		    Cor-
     rect behavior
	LWG 2981 C++17	    redundant deduction guide from		     re-
     moved
			    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)

http://cppreference.com 	   2024.06.10		     std::unique_lock(3)
home | help