QP/C++  7.0.1
Real-Time Embedded Framework
QXSemaphore Class Reference

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

#include <qxthread.hpp>

Public Member Functions

void init (std::uint_fast16_t const count, std::uint_fast16_t const max_count=0xFFFFU) noexcept
 initialize the counting semaphore More...
 
bool wait (std::uint_fast16_t const nTicks=QXTHREAD_NO_TIMEOUT) noexcept
 wait (block) on the semaphore More...
 
bool tryWait (void) noexcept
 try wait on the semaphore (non-blocking) More...
 
bool signal (void) noexcept
 signal (unblock) the semaphore More...
 

Private Attributes

QPSet m_waitSet
 set of extended threads waiting on this semaphore More...
 
std::uint16_t volatile m_count
 semaphore up-down counter More...
 
std::uint16_t m_max_count
 maximum value of the semaphore counter More...
 

Detailed Description

Description
QP::QXSemaphore is a blocking mechanism intended primarily for signaling extended threads. The semaphore is initialized with the maximum count (see QP::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
BTN_sema.init(0U, // initial semaphore count (singaling semaphore)
1U); // maximum semaphore count (binary semaphore)
. . .
}
void main_threadXYZ(QXThread * const me) {
while (1) {
. . .
BTN_sema.wait(QXTHREAD_NO_TIMEOUT); // timeout for waiting
. . .
}
}
void GPIO_Handler(void) {
. . .
BTN_sema.signal();
. . .
}
Counting Semaphore of the QXK preemptive kernel.
Definition: qxthread.hpp:145
bool wait(std::uint_fast16_t const nTicks=QXTHREAD_NO_TIMEOUT) noexcept
wait (block) on the semaphore
Definition: qxk_sema.cpp:108
bool signal(void) noexcept
signal (unblock) the semaphore
Definition: qxk_sema.cpp:231
void init(std::uint_fast16_t const count, std::uint_fast16_t const max_count=0xFFFFU) noexcept
initialize the counting semaphore
Definition: qxk_sema.cpp:75
Extended (blocking) thread of the QXK preemptive kernel.
Definition: qxthread.hpp:58
static constexpr std::uint_fast16_t QXTHREAD_NO_TIMEOUT
no-timeout sepcification when blocking on queues or semaphores
Definition: qxthread.hpp:37

Definition at line 145 of file qxthread.hpp.

Member Function Documentation

◆ init()

void init ( std::uint_fast16_t const  count,
std::uint_fast16_t const  max_count = 0xFFFFU 
)
noexcept
Description
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]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.
Note
QXSemaphore::init() must be called before the semaphore can be used (signaled or waited on).
Precondition
max_count must be greater than zero

Definition at line 75 of file qxk_sema.cpp.

◆ wait()

bool wait ( std::uint_fast16_t const  nTicks = QXTHREAD_NO_TIMEOUT)
noexcept
Description
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]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 the timeout occurred.
Note
Multiple extended threads can wait for a given semaphore.
Precondition
this function 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.
also: the thread must NOT be holding a scheduler lock.

Definition at line 108 of file qxk_sema.cpp.

◆ tryWait()

bool tryWait ( void  )
noexcept
Description
This operation checks if the semaphore counter is greater than 0, in which case the counter is decremented.
Returns
'true' if the semaphore has count available and 'false' NOT available.
Note
This function can be called from any context, including ISRs and basic threads (active objects).
Precondition
the semaphore must be initialized

Definition at line 192 of file qxk_sema.cpp.

◆ signal()

bool signal ( void  )
noexcept
Description
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.
Returns
'true' when the semaphore gets signaled and 'false' when the semaphore count exceeded the maximum.
Note
A semaphore can be signaled from many places, including from ISRs, basic threads (AOs), and extended threads.
Precondition
the semaphore must be initialized

Definition at line 231 of file qxk_sema.cpp.

Field Documentation

◆ m_waitSet

QPSet m_waitSet
private

Definition at line 161 of file qxthread.hpp.

◆ m_count

std::uint16_t volatile m_count
private

Definition at line 162 of file qxthread.hpp.

◆ m_max_count

std::uint16_t m_max_count
private

Definition at line 163 of file qxthread.hpp.


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