QXMutex Class Reference

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

#include <qxk.h>

Public Member Functions
void	QXMutex_init (QXMutex *const me, QPrioSpec const prioSpec)
	Initialize the QXK priority-ceiling mutex QXMutex.
bool	QXMutex_lock (QXMutex *const me, QTimeEvtCtr const nTicks)
	Lock the QXK priority-ceiling mutex QXMutex.
bool	QXMutex_tryLock (QXMutex *const me)
	Try to lock the QXK priority-ceiling mutex QXMutex.
void	QXMutex_unlock (QXMutex *const me)
	Unlock the QXK priority-ceiling mutex QXMutex.

Private Member Functions
bool	QXMutex_tryAcq_ (QXMutex *const me, QXThread *const curr)
void	QXMutex_relOneThr_ (QXMutex *const me)

Private Attributes
QActive	ao
	Active object used as a placeholder AO for this mutex in QActive_registry_[].
QPSet	waitSet
	Set of extended-threads waiting on this mutex.

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;
}

Definition at line 165 of file qxk.h.

Member Function Documentation

QXMutex_init()

void QXMutex_init	(	QXMutex *const	me,
		QPrioSpec const	prioSpec )

Initialize the QXK priority-ceiling mutex QXMutex.

Details
Initialize the QXK priority ceiling mutex.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	prioSpec	the priority specification for the mutex (See also QPrioSpec). This value might also be zero.

Note

prioSpec == 0 means that the priority-ceiling protocol shall not be used by this mutex. Such mutex will not change (boost) the priority of the holding threads.

Conversely, prioSpec != 0 means that the priority-ceiling protocol shall be used by this mutex. Such mutex will temporarily boost the priority and priority-threshold of the holding thread to the priority specification in prioSpec (see QPrioSpec).

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;
}

Definition at line 48 of file qxk_mutex.c.

QXMutex_lock()

bool QXMutex_lock	(	QXMutex *const	me,
		QTimeEvtCtr const	nTicks )

Lock the QXK priority-ceiling mutex QXMutex.

Details

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	nTicks	number of clock ticks (at the associated rate) to wait for the mutex. The value of QXTHREAD_NO_TIMEOUT indicates that no timeout will occur and the mutex could block indefinitely.

Returns

'true' if the mutex has been acquired and 'false' if a timeout occurred.

Note

The mutex locks are allowed to nest, meaning that the same extended thread can lock the same mutex multiple times (< 255). However, each call to QXMutex_lock() must be balanced by the matching call to QXMutex_unlock().

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;
}

Definition at line 151 of file qxk_mutex.c.

QXMutex_tryLock()

bool QXMutex_tryLock

(

QXMutex *const

me

)

Try to lock the QXK priority-ceiling mutex QXMutex.

Details

Parameters

[in,out]

me

current instance pointer (see SAS_QP_OOA)

Returns

'true' if the mutex was successfully locked and 'false' if the mutex was unavailable and was NOT locked.

Note

This function can be called from both basic threads (active objects) and extended threads.

The mutex locks are allowed to nest, meaning that the same extended thread can lock the same mutex multiple times (<= 255). However, each successful call to QXMutex_tryLock() must be balanced by the matching call to QXMutex_unlock().

Definition at line 224 of file qxk_mutex.c.

QXMutex_unlock()

void QXMutex_unlock

(

QXMutex *const

me

)

Unlock the QXK priority-ceiling mutex QXMutex.

Details

Parameters

[in,out]

me

current instance pointer (see SAS_QP_OOA)

Note

This function can be called from both basic threads (active objects) and extended threads.

The mutex locks are allowed to nest, meaning that the same extended thread can lock the same mutex multiple times (<= 225). However, each call to QXMutex_lock() or a successful call to QXMutex_tryLock() must be balanced by the matching call to QXMutex_unlock().

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;
}

Definition at line 257 of file qxk_mutex.c.

QXMutex_tryAcq_()

bool QXMutex_tryAcq_ ( QXMutex *const me, QXThread *const curr )

private

Definition at line 69 of file qxk_mutex.c.

QXMutex_relOneThr_()

void QXMutex_relOneThr_ ( QXMutex *const me )

private

Definition at line 334 of file qxk_mutex.c.

Member Data Documentation

ao

QActive ao

private

Active object used as a placeholder AO for this mutex in QActive_registry_[].

Definition at line 166 of file qxk.h.

waitSet

QPSet waitSet

private

Set of extended-threads waiting on this mutex.

Definition at line 167 of file qxk.h.

---

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

• qxk.h
• qxk_mutex.c
• qxk.dox