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

The priority_mutex is an advanced synchronization mechanism that enhances the traditional mutex by introducing a priority-based approach.
It serves to protect shared data from simultaneous access by multiple threads and provides exclusive, non-recursive ownership semantics: More...

#include <priority_mutex_cpl.hpp>

Public Member Functions
void	lock (Priority_t const priority=0)
	Acquire the 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. However, if lock() is invoked by a thread that already possesses the mutex, this results in undefined behavior, potentially causing a program deadlock. An implementation capable of identifying this invalid usage is encouraged to raise a std::system_error exception with the error condition resource_deadlock_would_occur instead of risking a deadlock. Moreover, any previous unlock() operations on the same mutex are synchronize-with this operation, following the semantics defined in std::memory_order.
bool	try_lock (Priority_t const priority=0)
	Try to acquire the unique ownership of the 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 designed to potentially fail without a specific reason, even if the mutex is not presently locked by any other thread. However, invoking try_lock() when a thread already holds the mutex results in undefined behavior. 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. It's important to note that if try_lock() returns false, prior lock() calls do not establish a synchronization relationship with this operation.
void	unlock ()
	Unlocks the priority-mutex. It is essential for the priority-mutex to be held by the current thread of execution; otherwise, the outcome is undefined. This operation synchronizes-with (as defined in std::memory_order) any subsequent lock operation that obtains ownership of the same priority-mutex.

Detailed Description

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

The priority_mutex is an advanced synchronization mechanism that enhances the traditional mutex by introducing a priority-based approach.
It serves to protect shared data from simultaneous access by multiple threads and provides exclusive, non-recursive ownership semantics:

• A thread holds a priority_mutex from the moment it successfully calls either lock() or try_lock() until it calls unlock().
• While a thread owns a priority_mutex, all other threads attempting to acquire ownership will either block (in the case of lock()) or receive a false return value (with try_lock()).
• It's important to note that a thread should not possess the mutex prior to calling lock() or try_lock().

The program's behavior becomes unpredictable when a priority_mutex is destroyed while it's still under the ownership of any threads or when a thread terminates while in possession of a priority_mutex.
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 priority_mutex class complies with all Mutex and StandardLayoutType requirements.
Importantly, priority_mutex is neither copyable nor movable.

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::priority_mutex< N >::lock ( Priority_t const  priority = 0 )

inline

Acquire the 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.
However, if lock() is invoked by a thread that already possesses the mutex, this results in undefined behavior, potentially causing a program deadlock. An implementation capable of identifying this invalid usage is encouraged to raise a std::system_error exception with the error condition resource_deadlock_would_occur instead of risking a deadlock.
Moreover, any previous unlock() operations on the same mutex are synchronize-with this operation, following the semantics 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

(none)

Exceptions

std::system_error

Throws std::system_error in the event of errors, including those originating from the underlying operating system that would impede the lock() operation from meeting its specifications. It's important to note that no locking occurs if an exception is thrown.

Example

#include <boost/fairness.hpp>
#include <iostream>
#define NUM_ARBITRARY_PRIORITIES 5
 
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::priority_mutex< N >::try_lock ( Priority_t const  priority = 0 )

inline

Try to acquire the unique ownership of the 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 designed to potentially fail without a specific reason, even if the mutex is not presently locked by any other thread.
However, invoking try_lock() when a thread already holds the mutex results in undefined behavior.
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.
It's important to note that if try_lock() returns false, prior lock() calls do not establish a synchronization relationship with 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

[[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
 
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::priority_mutex< N >::unlock ( )

inline

Unlocks the priority-mutex.
It is essential for the priority-mutex to be held by the current thread of execution; otherwise, the outcome is undefined.
This operation synchronizes-with (as defined in std::memory_order) any subsequent lock operation that obtains ownership of the same priority-mutex.

Parameters

(none)

Returns

(none)

Exceptions

Throws

nothing.

Example

#include <boost/fairness.hpp>
#include <iostream>
#define NUM_ARBITRARY_PRIORITIES 5
 
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 files:

• include/boost/fairness/priority_mutex_cpl.hpp
• include/boost/fairness/priority_mutex_tatas.hpp