QP/C  7.2.2
Real-Time Embedded Framework
Loading...
Searching...
No Matches
QXSemaphore Class Reference

Counting Semaphore of the QXK preemptive kernel. More...

#include "qxk.h"

Public Member Functions

void QXSemaphore_init (QXSemaphore *const me, uint_fast8_t const count, uint_fast8_t const max_count)
 
bool QXSemaphore_wait (QXSemaphore *const me, uint_fast16_t const nTicks)
 
bool QXSemaphore_tryWait (QXSemaphore *const me)
 
bool QXSemaphore_signal (QXSemaphore *const me)
 

Public Attributes

QPSet waitSet
 
uint8_t volatile count
 
uint8_t max_count
 

Detailed Description

QXSemaphore is a blocking mechanism intended primarily for signaling extended threads. The semaphore is initialized with the maximum count (see QXSemaphore_init()), which allows you to create a binary semaphore (when the maximum count is 1) and counting semaphore when the maximum count is > 1.

Usage
The following example illustrates how to instantiate and use the semaphore in your application.
QXSemaphore BTN_sema; /* semaphore to signal a button press */
int main() {
. . .
/* initialize the BTN_sema semaphore as binary, signaling semaphore */
QXSemaphore_init(&BTN_sema, /* pointer to semaphore to initialize */
0U, /* initial semaphore count (singaling semaphore) */
1U); /* maximum semaphore count (binary semaphore) */
. . .
}
void main_threadXYZ(QXThread * const me) {
while (1) {
. . .
QXSemaphore_wait(&BTN_sema, /* <--- pointer to semaphore to wait on */
QXTHREAD_NO_TIMEOUT); /* timeout for waiting */
. . .
}
}
void GPIO_Handler(void) {
. . .
QXSemaphore_signal(&BTN_sema); /* <--- pointer to semaphore to signal */
. . .
}
#define QXTHREAD_NO_TIMEOUT
Definition: qxk.h:944
Counting Semaphore of the QXK preemptive kernel.
Definition: qxk.h:615
bool QXSemaphore_signal(QXSemaphore *const me)
Definition: qxk_sema.c:206
bool QXSemaphore_wait(QXSemaphore *const me, uint_fast16_t const nTicks)
Definition: qxk_sema.c:87
void QXSemaphore_init(QXSemaphore *const me, uint_fast8_t const count, uint_fast8_t const max_count)
eXtended (blocking) thread of the QXK preemptive kernel
Definition: qxk.h:289

Definition at line 615 of file qxk.h.

Member Function Documentation

◆ QXSemaphore_init()

void QXSemaphore_init ( QXSemaphore *const  me,
uint_fast8_t const  count,
uint_fast8_t const  max_count 
)

initialize the counting semaphore

Initializes a semaphore with the specified count and maximum count. If the semaphore is used for resource sharing, both the initial count and maximum count should be set to the number of identical resources guarded by the semaphore. If the semaphore is used as a signaling mechanism, the initial count should set to 0 and maximum count to 1 (binary semaphore).

Parameters
[in,out]mecurrent instance pointer (see oop)
[in]countinitial value of the semaphore counter
[in]max_countmaximum value of the semaphore counter. The purpose of the max_count is to limit the counter so that the semaphore cannot unblock more times than the maximum.
Precondition qxk_sema:100
  • max_count must be greater than zero
Note
QXSemaphore_init() must be called before the semaphore can be used (signaled or waited on).

◆ QXSemaphore_wait()

bool QXSemaphore_wait ( QXSemaphore *const  me,
uint_fast16_t const  nTicks 
)

wait (block) on the semaphore

When an extended thread calls QXSemaphore_wait() and the value of the semaphore counter is greater than 0, QXSemaphore_wait() decrements the semaphore counter and returns (true) to its caller. However, if the value of the semaphore counter is 0, the function places the calling thread in the waiting list for the semaphore. The thread waits until the semaphore is signaled by calling QXSemaphore_signal(), or the specified timeout expires. If the semaphore is signaled before the timeout expires, QXK resumes the highest-priority extended thread waiting for the semaphore.

Parameters
[in,out]mecurrent instance pointer (see oop)
[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 semaphore has been signaled and 'false' if a timeout occurred.
Precondition qxk_sema:200
  • must NOT be called from an ISR;
  • the semaphore must be initialized
  • be called from an extended thread;
  • the thread must NOT be already blocked on any object.
Precondition qxk_sema:201
  • the thread must NOT be holding a scheduler lock.
Note
Multiple extended threads can wait for a given semaphore.

Definition at line 87 of file qxk_sema.c.

◆ QXSemaphore_tryWait()

bool QXSemaphore_tryWait ( QXSemaphore *const  me)

try wait on the semaphore (non-blocking)

This function checks if the semaphore counter is greater than 0, in which case the counter is decremented.

Parameters
[in,out]mecurrent instance pointer (see oop)
Returns
'true' if the semaphore has count available and 'false' NOT available.
Precondition qxk_sema:300
  • the semaphore must be initialized
Note
This function can be called from any context, including ISRs and basic threads (active objects).

Definition at line 166 of file qxk_sema.c.

◆ QXSemaphore_signal()

bool QXSemaphore_signal ( QXSemaphore *const  me)

signal (unblock) the semaphore

If the semaphore counter value is 0 or more, it is incremented, and this function returns to its caller. If the extended threads are waiting for the semaphore to be signaled, QXSemaphore_signal() removes the highest- priority thread waiting for the semaphore from the waiting list and makes this thread ready-to-run. The QXK scheduler is then called to determine if the awakened thread is now the highest-priority thread that is ready-to-run.

Parameters
[in,out]mecurrent instance pointer (see oop)
Returns
'true' when the semaphore signaled and 'false' when the semaphore count exceeded the maximum.
Precondition qxk_sema:400
  • the semaphore must be initialized
Note
A semaphore can be signaled from many places, including from ISRs, basic threads (AOs), and extended threads.

Definition at line 206 of file qxk_sema.c.

Member Data Documentation

◆ waitSet

QPSet QXSemaphore::waitSet

set of extended threads waiting on this semaphore

Definition at line 619 of file qxk.h.

◆ count

uint8_t volatile QXSemaphore::count

semaphore up-down counter

Definition at line 622 of file qxk.h.

◆ max_count

uint8_t QXSemaphore::max_count

maximum value of the semaphore counter

Definition at line 625 of file qxk.h.


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