QP/C++  6.5.1
QXMutex Class Reference

Priority Ceiling Mutex the QXK preemptive kernel. More...

#include <qxthread.h>

Collaboration diagram for QXMutex:
Collaboration graph

Public Member Functions

void init (uint_fast8_t const ceiling)
 initialize the QXK priority-ceiling mutex QP::QXMutex More...
 
bool lock (uint_fast16_t const nTicks=QXTHREAD_NO_TIMEOUT)
 lock the QXK priority-ceiling mutex QP::QXMutex More...
 
bool tryLock (void)
 try to lock the QXK priority-ceiling mutex QP::QXMutex More...
 
void unlock (void)
 unlock the QXK priority-ceiling mutex QP::QXMutex More...
 

Private Attributes

QPSet m_waitSet
 set of extended-threads waiting on this mutex More...
 
uint8_t volatile m_lockNest
 lock-nesting up-down counter More...
 
uint8_t volatile m_holderPrio
 priority of the lock holder thread More...
 
uint8_t m_ceiling
 

Detailed Description

Priority Ceiling Mutex the QXK preemptive kernel.

Description
QP::QXMutex is a blocking mutual exclusion mechanism that can also apply the priority ceiling protocol to avoid unbounded priority inversion (if initialized with a non-zero ceiling priority, see QP::QXMutex::init()). In that case, QP::QXMutex requires its own uinque QP priority level, which cannot be used by any thread or any other QP::QXMutex. If initialzied with zero ceiling priority, QP::QXMutex does not use the priority ceiling protocol and does not require a unique QP priority (see QP::QXMutex::init()). QP::QXMutex is recursive (reentrant), which means that it can be locked mutiliple times (up to 255 levels) by the same thread without causing deadlock. QP::QXMutex is primarily intended for the extened (blocking) threads, but can also be used by the basic threads through the non-blocking QP::QXMutex::tryLock() API.
Note
QP::QXMutex should be used in situations when at least one of the extended threads contending for the mutex blocks while holding the mutex (between the QP::QXMutex::lock() and QP::QXMutex::unlock() operations). If no blocking is needed while holding the mutex, the more efficient non-blocking mechanism of selective QXKscheduler locking" should be used instead. @ref QP::QXK::schedLock() "Selective scheduler locking" is available for both @ref QP::QActive "basic threads" and @ref QP::QXThread "extended threads", so it is applicable to situations where resources are shared among all these threads.
Usage
The following example illustrates how to instantiate and use the mutex in your application.
QXMutex l_rndMutex; // mutex to protect the random number generator
void BSP::randomSeed(uint32_t seed) {
l_rndMutex.init(N_PHILO + 1); // <== initialize the mutex
l_rnd = seed;
}
uint32_t BSP::random(void) { // a very cheap pseudo-random-number generator
uint32_t rnd;
l_rndMutex.lock(); // <== lock the shared random seed
// "Super-Duper" Linear Congruential Generator (LCG)
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; // set for the next time
l_rndMutex.unlock(); // <== unlock the shared random seed
return rnd;
}

Definition at line 219 of file qxthread.h.

Member Function Documentation

◆ init()

void init ( uint_fast8_t const  ceiling)

initialize the QXK priority-ceiling mutex QP::QXMutex

◆ lock()

bool lock ( uint_fast16_t const  nTicks = QXTHREAD_NO_TIMEOUT)

lock the QXK priority-ceiling mutex QP::QXMutex

◆ tryLock()

bool tryLock ( void  )

try to lock the QXK priority-ceiling mutex QP::QXMutex

◆ unlock()

void unlock ( void  )

unlock the QXK priority-ceiling mutex QP::QXMutex

Field Documentation

◆ m_waitSet

QPSet m_waitSet
private

set of extended-threads waiting on this mutex

Definition at line 234 of file qxthread.h.

◆ m_lockNest

uint8_t volatile m_lockNest
private

lock-nesting up-down counter

Definition at line 235 of file qxthread.h.

◆ m_holderPrio

uint8_t volatile m_holderPrio
private

priority of the lock holder thread

Definition at line 236 of file qxthread.h.

◆ m_ceiling

uint8_t m_ceiling
private

Definition at line 237 of file qxthread.h.


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