QP/C  5.9.7
qxk_mutex.c File Reference

QXMutex_init(), QXMutex_lock 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.

Macros

#define QP_IMPL   /* this is QP implementation */
 

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

QXMutex_init(), QXMutex_lock and QXMutex_unlock() definitions.

Definition in file qxk_mutex.c.

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]ceilingceiling priotity of the mutex
Note
The ceiling priority must be unused by any thread. The ceiling priority must be higher than priority of any thread that uses the protected resource.
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:
  • not be zero;
  • 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 72 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 (<= 225). 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 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 117 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 thread priority must be below the ceiling of the mutex;
  • the thread must NOT be holding a scheduler lock;

Definition at line 218 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 holding thread must have priority equal to the mutex ceiling;
  • the mutex must be already locked at least once.

Definition at line 297 of file qxk_mutex.c.