The shared_priority_mutex is an advanced synchronization mechanism that enhances the traditional shared_mutex by introducing a priority-based approach.
The shared_priority_mutex class is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads. In contrast to other mutex types which facilitate exclusive access, a shared_mutex has two levels of access: More...

#include <shared_priority_mutex.hpp>

Public Member Functions
void	lock (Priority_t const priority=0)
	Try to acquire the unique ownership of the shared_priority_mutex, blocking the thread if the shared_priority_mutex was already owned or other threads are waiting with higher priority. If another thread is holding an exclusive lock() or a shared_lock() on the same shared_priority_mutex the a call to lock will block execution until all such locks are released. While shared_priority_mutex is locked in an exclusive mode, no other lock() of any kind can also be held. If lock is called by a thread that already owns the shared_mutex in any mode (exclusive or shared), the behavior is undefined. A prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation.

void	lock_shared (Priority_t priority=0)
	Try to acquire the shared ownership of the shared_priority_mutex, blocking the thread if the shared_priority_mutex was already uniquely owned or if another thread is waiting for unique ownership with higher priority. If another thread is holding the mutex in exclusive ownership, a call to lock_shared will block execution until shared ownership can be acquired. If lock_shared() is called by a thread that already owns the mutex in any mode (exclusive or shared), the behavior is undefined. If more than the implementation-defined maximum number of shared owners already locked the mutex in shared mode, lock_shared blocks execution until the number of shared owners is reduced. The maximum number of owners is guaranteed to be at least 10000. A prior unlock() operation on the same mutex synchronizes-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 shared_priority_mutex, if successful will return `true`, `false` otherwise. This function is allowed to fail spuriously and return `false` even if the mutex is not currently locked by any other thread. If try_lock() is called by a thread that already owns the shared_priority_mutex in any mode (shared or exclusive), the behavior is undefined. Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns `true`. Note that prior lock() does not synchronize with this operation if it returns `false`.

bool	try_lock_shared (Priority_t priority=0)
	Try to acquire the shared ownership of the shared_priority_mutex, if successful will return `true`, `false` otherwise. This function is allowed to fail spuriously and return `false` even if the mutex is not currenly exclusively locked by any other thread. A prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns `true`. The behavior is undefined if the calling thread already owns the mutex in any mode.

void	unlock ()
	Release the shared_priority_mutex from unique ownership. The mutex must be locked by the current thread of execution, otherwise, the behavior is undefined. This operation synchronizes-with (as defined in std::memory_order) any subsequent lock operation that obtains ownership of the same mutex.

void	unlock_shared ()
	Release the shared_priority_mutex from shared ownership by the calling thread. The mutex shared_priority_mutex be locked by the current thread of execution in shared mode, otherwise, the behavior is undefined. This operation synchronizes-with (as defined in std::memory_order) any subsequent lock() operation that obtains ownership of the same shared_priority_mutex.

Detailed Description

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

The shared_priority_mutex is an advanced synchronization mechanism that enhances the traditional shared_mutex by introducing a priority-based approach.
The shared_priority_mutex class is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads. In contrast to other mutex types which facilitate exclusive access, a shared_mutex has two levels of access:

shared - several threads can share ownership of the same mutex;
exclusive - only one thread can own the mutex.

If one thread has acquired the exclusive lock (through lock(), try_lock()), no other threads can acquire the lock (including the shared).
If one thread has acquired the shared lock (through lock_shared(), try_lock_shared()), no other thread can acquire the exclusive lock, but can acquire the shared lock.
Only when the exclusive lock has not been acquired by any thread, the shared lock can be acquired by multiple threads.
Within one thread, only one lock (shared or exclusive) can be acquired at the same time.
Shared mutexes are especially useful when shared data can be safely read by any number of threads simultaneously, but a thread may only write the same data when no other thread is reading or writing at the same time.
The shared_priority_mutex class satisfies all requirements of SharedMutex and StandardLayoutType.

Template Parameters

N	: number of 0 indexed priorities the shared_priority_mutex manages, up to BOOST_FAIRNESS_MAXIMUM_PRIORITY.

Member Function Documentation

◆ lock()

template<size_t N = 1>

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

inline

Try to acquire the unique ownership of the shared_priority_mutex, blocking the thread if the shared_priority_mutex was already owned or other threads are waiting with higher priority.
If another thread is holding an exclusive lock() or a shared_lock() on the same shared_priority_mutex the a call to lock will block execution until all such locks are released. While shared_priority_mutex is locked in an exclusive mode, no other lock() of any kind can also be held.
If lock is called by a thread that already owns the shared_mutex in any mode (exclusive or shared), the behavior is undefined. A prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation.

Parameters

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

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.

Note: lock() is usually not called directly: unique_lock, scoped_lock, and lock_guard are used to manage exclusive locking.

Example

shared_priority_mutex<10> m;
 
void my_function(int prio) {
     //...some code.
     m.lock(prio);
     //...some code.
}

◆ lock_shared()

template<size_t N = 1>

void boost::fairness::shared_priority_mutex< N >::lock_shared ( Priority_t priority = 0 )

inline

Try to acquire the shared ownership of the shared_priority_mutex, blocking the thread if the shared_priority_mutex was already uniquely owned or if another thread is waiting for unique ownership with higher priority.
If another thread is holding the mutex in exclusive ownership, a call to lock_shared will block execution until shared ownership can be acquired.
If lock_shared() is called by a thread that already owns the mutex in any mode (exclusive or shared), the behavior is undefined.
If more than the implementation-defined maximum number of shared owners already locked the mutex in shared mode, lock_shared blocks execution until the number of shared owners is reduced. The maximum number of owners is guaranteed to be at least 10000.
A prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation.

Parameters

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

Returns: none.

Exceptions

std::system_error : Throws [std::system_error](https://en.cppreference.com/w/cpp/error/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.

Note: lock_shared() is usually not called directly: shared_lock is used to manage shared locking.

Example

shared_priority_mutex<10> m;
 
void my_function(int prio) {
     //...some code.
     m.lock_shared(prio);
     //...some code.
}

◆ try_lock()

template<size_t N = 1>

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

inline

Try to acquire the unique ownership of the shared_priority_mutex, if successful will return true, false otherwise.
This function is allowed to fail spuriously and return false even if the mutex is not currently locked by any other thread.
If try_lock() is called by a thread that already owns the shared_priority_mutex in any mode (shared or exclusive), the behavior is undefined.
Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true. Note that prior lock() does not synchronize with this operation if it returns false.

Parameters

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

Returns: true : if the lock was acquired successfully.; false : otherwise.

Exceptions

Throws nothing.

Example

shared_priority_mutex<10> m;
 
void my_function(int prio) {
     //...some code.
     m.try_lock(prio);
     //...some code.
}

◆ try_lock_shared()

template<size_t N = 1>

bool boost::fairness::shared_priority_mutex< N >::try_lock_shared ( Priority_t priority = 0 )

inline

Try to acquire the shared ownership of the shared_priority_mutex, if successful will return true, false otherwise.
This function is allowed to fail spuriously and return false even if the mutex is not currenly exclusively locked by any other thread.
A prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true.
The behavior is undefined if the calling thread already owns the mutex in any mode.

Parameters

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

Returns: true : if the lock was acquired successfully.; false : otherwise.

Exceptions

Throws nothing.

Example

shared_priority_mutex<10> m;
 
void my_function(int prio) {
     //...some code.
     m.try_lock_shared(prio);
     //...some code.
}

Returns: bool

◆ unlock()

template<size_t N = 1>

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

inline

Release the shared_priority_mutex from unique ownership.
The mutex must be locked by the current thread of execution, otherwise, the behavior is undefined.
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

none.

Note: unlock() is usually not called directly: unique_lock and lock_guard are used to manage exclusive locking.

Example

shared_priority_mutex<10> m;
 
void my_function() {
     //...some code.
     m.unlock();
     //...some code.
}

◆ unlock_shared()

template<size_t N = 1>

void boost::fairness::shared_priority_mutex< N >::unlock_shared ( )

inline

Release the shared_priority_mutex from shared ownership by the calling thread.
The mutex shared_priority_mutex be locked by the current thread of execution in shared mode, otherwise, the behavior is undefined.
This operation synchronizes-with (as defined in std::memory_order) any subsequent lock() operation that obtains ownership of the same shared_priority_mutex.

Parameters

none.

Returns: none.

Exceptions

Throws nothing.

Note: unlock_shared() is usually not called directly: shared_lock is used to manage shared locking.

Example

shared_priority_mutex<10> m;
 
void my_function() {
     //...some code.
     m.unlock_shared();
     //...some code.
}

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

include/boost/fairness/shared_priority_mutex.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ lock()

Example

◆ lock_shared()

Example

◆ try_lock()

Example

◆ try_lock_shared()

Example

◆ unlock()

Example

◆ unlock_shared()

Example