QP/C  6.0.0
qxk_mutex.c File Reference

QXMutex_init(), QXMutex_lock(), QXMutex_tryLock() and QXMutex_unlock() definitions. More...

#include "qf_port.h"
#include "qxk_pkg.h"
#include "qassert.h"
#include "qs_port.h"

Go to the source code of this file.

Functions

void QXMutex_init (QXMutex *const me, uint_fast8_t ceiling)
 initialize the QXK priority-ceiling mutex QXMutex More...
 
bool QXMutex_lock (QXMutex *const me, uint_fast16_t const nTicks)
 lock the QXK priority-ceiling mutex QXMutex More...
 
bool QXMutex_tryLock (QXMutex *const me)
 try to lock the QXK priority-ceiling mutex QXMutex More...
 
void QXMutex_unlock (QXMutex *const me)
 unlock the QXK priority-ceiling mutex QXMutex More...
 

Detailed Description

Function Documentation

◆ QXMutex_init()

void QXMutex_init ( QXMutex *const  me,
uint_fast8_t  ceiling 
)

initialize the QXK priority-ceiling mutex QXMutex

Description
Initialize the QXK priority ceiling mutex.
Parameters
[in,out]mepointer (see Object Orientation)
[in]ceilingthe ceiling-priotity of this mutex or zero
Note
ceiling == 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 thread.
ceiling > 0 means that the priority-ceiling protocol shall be used by this mutex. Such mutex will boost the priority of the holding thread to the ceiling level for as long as the thread holds this mutex.
Attention
When the priority-ceiling protocol is used (ceiling > 0), the ceiling priority must be unused by any other thread or mutex. Also, the ceiling priority must be higher than priority of any thread that uses this mutex.
Usage
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 very cheap pseudo-random-number generator */
uint32_t rnd;
QXMutex_lock(&l_rndMutex); /* <== 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 */
QXMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}
Precondition
the celiling priority of the mutex must:
  • cannot exceed the maximum QF_MAX_ACTIVE;
  • the ceiling priority of the mutex must not be already in use; (QF requires priority to be unique).

Definition at line 85 of file qxk_mutex.c.

◆ QXMutex_lock()

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

lock the QXK priority-ceiling mutex QXMutex

Description
Lock the QXK priority ceiling mutex QXMutex.
Parameters
[in,out]mepointer (see Object Orientation)
[in]nTicksnumber of clock ticks (at the associated rate) to wait for the semaphore. The value of QXTHREAD_NO_TIMEOUT indicates that no timeout will occur and the semaphore will wait indefinitely.
Returns
'true' if the mutex has been acquired and 'false' if a timeout occured.
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 ballanced by the matching call to QXMutex_unlock().
Usage
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 very cheap pseudo-random-number generator */
uint32_t rnd;
QXMutex_lock(&l_rndMutex); /* <== 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 */
QXMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}
Precondition
this function must:
  • NOT be called from an ISR;
  • be called from an extended thread;
  • the ceiling priority must not be used; or if used
    • the thread priority must be below the ceiling of the mutex;
  • the thread must NOT be holding a scheduler lock;
  • the thread must NOT be already blocked on any object.

Definition at line 131 of file qxk_mutex.c.

◆ QXMutex_tryLock()

bool QXMutex_tryLock ( QXMutex *const  me)

try to lock the QXK priority-ceiling mutex QXMutex

Description
Try to lock the QXK priority ceiling mutex QXMutex.
Parameters
[in,out]mepointer (see Object Orientation)
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 (<= 225). However, each successful call to QXMutex_tryLock() must be ballanced by the matching call to QXMutex_unlock().
Precondition
this function must:
  • NOT be called from an ISR;
  • the QXK kernel must be running;
  • the calling thread must be valid;
  • the ceiling must be not used; or
    • the thread priority must be below the ceiling of the mutex;
  • the thread must NOT be holding a scheduler lock;

Definition at line 241 of file qxk_mutex.c.

◆ QXMutex_unlock()

void QXMutex_unlock ( QXMutex *const  me)

unlock the QXK priority-ceiling mutex QXMutex

Description
Unlock the QXK priority ceiling mutex.
Parameters
[in,out]mepointer (see Object Orientation)
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 successfull call to QXMutex_tryLock() must be ballanced by the matching call to QXMutex_unlock().
Usage
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 very cheap pseudo-random-number generator */
uint32_t rnd;
QXMutex_lock(&l_rndMutex); /* <== 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 */
QXMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}
Precondition
this function must:
  • NOT be called from an ISR;
  • the calling thread must be valid;
  • the mutex must be held by this thread;
  • the ceiling must not be used or
    • the current thread must have priority equal to the mutex ceiling;
  • the mutex must be already locked at least once.

Definition at line 331 of file qxk_mutex.c.