Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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
       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  require-
       ments (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	 Basi-
       cLockable
		  requirements

Member 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  associ-
       ated mutex without
	  try_lock	 blocking
			 (public member	function)
			 attempts to lock (i.e., takes ownership of) the asso-
       ciated
	  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  associ-
       ated TimedLockable
	  try_lock_until  mutex, returns if the	mutex has been unavailable un-
       til 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 <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 retroac-
       tively 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 wrap-
       per
	  (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		  2022.07.31		   std::unique_lock(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::unique_lock&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help