boost::fairness::recursive_priority_mutex< N > Class Template Reference

The recursive_priority_mutex is an advanced synchronization mechanism that enhances the traditional mutex by introducing a priority-based approach.
The recursive_priority_mutex can be used to protect shared data from being simultaneously accessed by multiple threads.
recursive_priority_mutex offers exclusive, recursive ownership semantics: More...

#include <recursive_priority_mutex.hpp>

Public Member Functions
void	lock (Priority_t const priority=0)
	Acquire the recursive_priority_mutex with a designated priority. If another thread has already obtained the lock, or if there are other threads waiting with higher priority, the lock() function will halt the current thread's execution until the lock is successfully obtained. A thread may call lock on a recursive_priority_mutex repeatedly. Ownership will only be released after the thread makes a matching number of calls to unlock. The maximum number of levels of ownership is unspecified. An exception of type std::system_error will be thrown if this number is exceeded. Prior unlock() operations on the same mutex synchronize-with (as defined in std::memory_order) this operation.
bool	try_lock (Priority_t const priority=0)
	Try to acquire the unique ownership of the recursive_priority_mutex with a designated priority. Returns immediately. On successful lock acquisition returns true, otherwise returns false. The return value must be used, otherwise the compiler is encouraged to issue a warning. This function is allowed to fail spuriously and return false even if the mutex is not currently locked by any other thread. A thread can make multiple consecutive calls to try_lock() on a recursive_priority_mutex. Each successful try_lock() call increments the ownership count, and the recursive_priority_mutex will only be released when the thread matches this count with an equivalent number of calls to unlock(). The maximum number of ownership levels remains unspecified. If this number is exceeded, a call to try_lock() will return false. If try_lock() returns true, any preceding unlock() operation on the same mutex is synchronized-with the current operation, as defined in std::memory_order.
void	unlock ()
	Unlock the recursive_priority_mutex when its ownership level is 1, signifying that there was precisely one more call to lock() than there were calls to unlock() made by the current thread. In all other cases, it reduces the ownership level by 1. For proper functioning, the mutex must be currently held by the executing thread. Any other scenario results in undefined behavior. This operation synchronizes-with (as defined in std::memory_order) any subsequent lock operation that obtains ownership of the same mutex.

Detailed Description

template<size_t N = 1>
requires (N >= 1 && N <= BOOST_FAIRNESS_MAXIMUM_PRIORITY)
class boost::fairness::recursive_priority_mutex< N >

The recursive_priority_mutex is an advanced synchronization mechanism that enhances the traditional mutex by introducing a priority-based approach.
The recursive_priority_mutex can be used to protect shared data from being simultaneously accessed by multiple threads.
recursive_priority_mutex offers exclusive, recursive ownership semantics:

• A calling thread owns a recursive_priority_mutex for a period of time that starts when it successfully calls either lock() or try_lock() until it calls unlock(). During this period, the thread may make additional calls to lock() or try_lock(). The period of ownership ends when the thread makes a matching number of calls to unlock().
• When a thread owns a recursive_priority_mutex, all other threads will block (for calls to lock()) or receive a false return value (for try_lock()) if they attempt to claim ownership of the recursive_priority_mutex.
• The maximum number of times that a recursive_priority_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_priority_mutex is destroyed while still owned by some thread.
Additionally, undefined behavior can occur when you specify a number of priorities (N) that falls outside the valid range, which should be between 1 and BOOST_FAIRNESS_MAXIMUM_PRIORITY.
The recursive_priority_mutex class satisfies all requirements of Mutex and StandardLayoutType.

Template Parameters

N	: represents the number of indexed priorities managed by the priority_mutex, ranging from 1 up to BOOST_FAIRNESS_MAXIMUM_PRIORITY.

Note

priority_mutex is usually not accessed directly: unique_lock, lock_guard, or scoped_lock manage locking in a more exception-safe manner.

Member Function Documentation

lock()

template<size_t N = 1>

void boost::fairness::recursive_priority_mutex< N >::lock ( Priority_t const  priority = 0 )

inline

Acquire the recursive_priority_mutex with a designated priority. If another thread has already obtained the lock, or if there are other threads waiting with higher priority, the lock() function will halt the current thread's execution until the lock is successfully obtained.
A thread may call lock on a recursive_priority_mutex repeatedly. Ownership will only be released after the thread makes a matching number of calls to unlock.
The maximum number of levels of ownership is unspecified. An exception of type std::system_error will be thrown if this number is exceeded.
Prior unlock() operations on the same mutex synchronize-with (as defined in std::memory_order) this operation.

Parameters

priority

used to set a priority for this thread to aquire the lock.

Warning

Undefined behavior occurs if the priority falls outside the range from 0 to N-1.

Returns

(none)

Exceptions

std::system_error

Throws std::system_error when errors occur, including errors from the underlying operating system that would prevent lock from meeting its specifications. The mutex is not locked in the case of any exception being thrown.

Example

#include <boost/fairness.hpp>
#include <iostream>
#define NUM_ARBITRARY_PRIORITIES 5
 
recursive_priority_mutex<NUM_ARBITRARY_PRIORITIES> m;
 
void my_function(uint8_t prio = 0) {
     //...some code.
     m.lock(prio));
     std::cout << "thread with prio : " << prio << "\n";
     //...some code.
}

Possible output:

thread with prio : 0

try_lock()

template<size_t N = 1>

bool boost::fairness::recursive_priority_mutex< N >::try_lock ( Priority_t const  priority = 0 )

inline

Try to acquire the unique ownership of the recursive_priority_mutex with a designated priority. Returns immediately.
On successful lock acquisition returns true, otherwise returns false. The return value must be used, otherwise the compiler is encouraged to issue a warning.
This function is allowed to fail spuriously and return false even if the mutex is not currently locked by any other thread.
A thread can make multiple consecutive calls to try_lock() on a recursive_priority_mutex. Each successful try_lock() call increments the ownership count, and the recursive_priority_mutex will only be released when the thread matches this count with an equivalent number of calls to unlock().
The maximum number of ownership levels remains unspecified. If this number is exceeded, a call to try_lock() will return false.
If try_lock() returns true, any preceding unlock() operation on the same mutex is synchronized-with the current operation, as defined in std::memory_order.

Parameters

priority

: used to set a priority for this thread to aquire the lock.

Warning

Undefined behavior occurs if the priority falls outside the range from 0 to N-1.

Returns

[[nodiscard]] bool : true if the lock was acquired successfully, otherwise false.

Exceptions

Throws

nothing.

Example

#include <boost/fairness.hpp>
#include <iostream>
#define NUM_ARBITRARY_PRIORITIES 5
 
recursive_priority_mutex<NUM_ARBITRARY_PRIORITIES> m;
 
void my_function(uint8_t prio = 0) {
     //...some code.
     if (m.try_lock(prio)) {
         std::cout << "thread with prio : " << prio << "\n";
     }
     //...some code.
}

Possible output:

thread with prio : 0

unlock()

template<size_t N = 1>

void boost::fairness::recursive_priority_mutex< N >::unlock ( )

inline

Unlock the recursive_priority_mutex when its ownership level is 1, signifying that there was precisely one more call to lock() than there were calls to unlock() made by the current thread. In all other cases, it reduces the ownership level by 1.
For proper functioning, the mutex must be currently held by the executing thread. Any other scenario results in undefined behavior.
This operation synchronizes-with (as defined in std::memory_order) any subsequent lock operation that obtains ownership of the same mutex.

Parameters

(none)

Returns

(none)

Exceptions

Throws

nothing.

Example

#include <boost/fairness.hpp>
#include <iostream>
#define NUM_ARBITRARY_PRIORITIES 5
 
recursive_priority_mutex<NUM_ARBITRARY_PRIORITIES> m;
 
void my_function() {
     //...some code.
     m.unlock();
     std::cout << "mutex unlocked \n";
     //...some code.
}

Possible output:

mutex unlocked

---

The documentation for this class was generated from the following file:

• include/boost/fairness/recursive_priority_mutex.hpp