QXMutex Class Reference

Blocking Mutex of the QXK preemptive kernel. More...

Detailed Description

Blocking Mutex of the QXK preemptive kernel.

Details

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 QXMutex_init()). In that case, QXMutex requires its own unique QP priority level, which cannot be used by any thread or any other QXMutex.

If initialized with preemption-ceiling of zero, QXMutex does not use the priority-ceiling protocol and does not require a unique QP priority (see QXMutex_init()).

QXMutex is recursive (re-entrant), which means that it can be locked multiple times (up to 255 levels) by the same thread without causing deadlock.

QXMutex is primarily intended for the extended (blocking) threads, but can also be used by the basic threads through the non-blocking QXMutex_tryLock() API.

Note

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 QXMutex_lock() and QXMutex_unlock() operations). If no blocking is needed while holding the mutex, the more efficient non-blocking mechanism of selective QXK scheduler locking should be used instead. Selective scheduler locking is available for both basic threads and 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 to protect a shared resource (random seed of a pseudo-random number generator).

QXMutex l_rndMutex;  // mutex to protect the random number generator
. . .
void BSP_randomSeed(uint32_t seed) {
    QXMutex_init(&l_rndMutex, N_PHILO); // <=== initialize the mutex
    l_rnd = seed;
}
. . .
uint32_t BSP_random(void) { // a pseudo-random-number generator
    uint32_t rnd;
 
    QXMutex_lock(&l_rndMutex); // <=== lock the shared random seed
    rnd = l_rnd * (3U*7U*11U*13U*23U);
    l_rnd = rnd; // set for the next time
    QXMutex_unlock(&l_rndMutex); // <=== unlock the shared random seed
 
    return rnd;
}

---

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

• qxk.dox