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

FreeBSD Manual Pages

  
 
  

home | help 
std::recursive_mutex(3)	      C++ Standard Libary      std::recursive_mutex(3)

NAME
       std::recursive_mutex - std::recursive_mutex

Synopsis
	  Defined in header <mutex>
	  class	recursive_mutex;     (since C++11)

	  The recursive_mutex class is a synchronization primitive that	can be
       used to protect
	  shared data from being simultaneously	accessed by multiple threads.

	  recursive_mutex offers exclusive, recursive ownership	semantics:

	    *  A  calling  thread  owns	a recursive_mutex for a	period of time
       that starts when	it
	      successfully calls either	lock or	try_lock. During this  period,
       the thread may
	      make  additional calls to	lock or	try_lock. The period of	owner-
       ship ends when the
	      thread makes a matching number of	calls to unlock.
	    * When a thread owns a recursive_mutex,  all  other	 threads  will
       block (for calls	to
	      lock) or receive a false return value (for try_lock) if they at-
       tempt to	claim
	      ownership	of the recursive_mutex.
	    * The maximum number of times that a recursive_mutex may be	locked
       is unspecified,
	      but  after  that	number	is  reached,  calls to lock will throw
       std::system_error and
	      calls to try_lock	will return false.

	  The behavior of a program is undefined if a recursive_mutex  is  de-
       stroyed while still
	  owned	 by  some  thread. The recursive_mutex class satisfies all re-
       quirements of Mutex
	  and StandardLayoutType.

Member types
	  Member type				 Definition
	  native_handle_type(not always	present) implementation-defined

Member functions
	  constructor	constructs the mutex
			(public	member function)
	  destructor	destroys the mutex
			(public	member function)
	  operator=	not copy-assignable
	  [deleted]	(public	member function)

Locking
	  lock		locks the mutex, blocks	if the mutex is	not available
			(public	member function)
	  try_lock	tries to lock the mutex, returns if the	mutex  is  not
       available
			(public	member function)
	  unlock	unlocks	the mutex
			(public	member function)

Native handle
	  native_handle	 returns  the underlying implementation-defined	native
       handle object
			(public	member function)

Example
	  one use case for recursive_mutex is protecting  shared  state	 in  a
       class whose member
	  functions may	call each other

       // Run this code

	#include <iostream>
	#include <thread>
	#include <mutex>

	class X	{
	    std::recursive_mutex m;
	    std::string	shared;
	  public:
	    void fun1()	{
	      std::lock_guard<std::recursive_mutex> lk(m);
	      shared = "fun1";
	      std::cout	 <<  "in  fun1,	 shared	variable is now	" << shared <<
       '\n';
	    }
	    void fun2()	{
	      std::lock_guard<std::recursive_mutex> lk(m);
	      shared = "fun2";
	      std::cout	<< "in fun2, shared variable is	now  "	<<  shared  <<
       '\n';
	      fun1(); // recursive lock	becomes	useful here
	      std::cout	 <<  "back  in fun2, shared variable is	" << shared <<
       '\n';
	    };
	};

	int main()
	{
	    X x;
	    std::thread	t1(&X::fun1, &x);
	    std::thread	t2(&X::fun2, &x);
	    t1.join();
	    t2.join();
	}

Possible output:
	in fun1, shared	variable is now	fun1
	in fun2, shared	variable is now	fun2
	in fun1, shared	variable is now	fun1
	back in	fun2, shared variable is fun1

See also
	  mutex	  provides basic mutual	exclusion facility
	  (C++11) (class)

http://cppreference.com		  2022.07.31	       std::recursive_mutex(3)

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

home | help