QP/C++  7.4.0-rc.1
Real-Time Embedded Framework
Loading...
Searching...
No Matches
QP::QXSemaphore Class Reference

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

#include "qxk.hpp"

Public Member Functions

void init (std::uint_fast8_t const count, std::uint_fast8_t const max_count=0xFFU) noexcept
 
bool wait (QTimeEvtCtr const nTicks=QXTHREAD_NO_TIMEOUT) noexcept
 
bool tryWait () noexcept
 
bool signal () noexcept
 

Private Attributes

QPSet m_waitSet
 
std::uint8_t m_count
 
std::uint8_t m_max_count
 

Detailed Description

Counting Semaphore of the QXK preemptive kernel.

Description
QP::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.
QP::QXSemaphore TH_sema; // <===
. . .
void XThread2::run(QP::QXThread * const thr) {
TH_sema.init(0U, // count==0 (signaling semaphore)
1U); // max_count==1 (binary semaphore)
for (;;) {
// wait on a semaphore (BLOCK indefinitely)
TH_sema.wait();
. . .
}
}
Counting Semaphore of the QXK preemptive kernel.
Definition qxk.hpp:142
void init(std::uint_fast8_t const count, std::uint_fast8_t const max_count=0xFFU) noexcept
Definition qxk_sema.cpp:77
bool wait(QTimeEvtCtr const nTicks=QXTHREAD_NO_TIMEOUT) noexcept
Definition qxk_sema.cpp:97
eXtended (blocking) thread of the QXK preemptive kernel
Definition qxk.hpp:88

Definition at line 142 of file qxk.hpp.

Member Function Documentation

◆ init()

void QP::QXSemaphore::init ( std::uint_fast8_t const count,
std::uint_fast8_t const max_count = 0xFFU )
noexcept

Initialize the counting semaphore

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.
Precondition qxk_sema:100
  • count must not exceed max_count
  • max_count must not be zero
  • max_count must not exceed 0xFFU (dynamic range of uint8_t)
Note
QXSemaphore::init() must be called before the semaphore can be used (signaled or waited on).
Usage
The following example illustrates how to instantiate and use the semaphore in your application.
. . .
void XThread2::run(QP::QXThread * const thr) {
TH_sema.init(0U, // count==0 (signaling semaphore) // <===
1U); // max_count==1 (binary semaphore)
for (;;) {
// wait on a semaphore (BLOCK indefinitely)
TH_sema.wait();
. . .
}
}
*/
//----------------------------------------------------------------------------
/*! @property QP::QXSemaphore::wait(std::uint_fast16_t const nTicks)
Wait (block) on the semaphore
@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.
@param[in] nTicks number 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 taken 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.
@usage
The following example illustrates how to instantiate and use the semaphore in your application.
@code{cpp}
QP::QXSemaphore TH_sema;
. . .
void XThread2::run(QP::QXThread * const thr) {
TH_sema.init(0U, // count==0 (signaling semaphore)
1U); // max_count==1 (binary semaphore)
for (;;) {
// wait on a semaphore (BLOCK indefinitely)
TH_sema.wait(); // <===
. . .
}
}

Definition at line 77 of file qxk_sema.cpp.

◆ wait()

bool QP::QXSemaphore::wait ( QTimeEvtCtr const nTicks = QXTHREAD_NO_TIMEOUT)
noexcept

Definition at line 97 of file qxk_sema.cpp.

◆ tryWait()

bool QP::QXSemaphore::tryWait ( )
noexcept

Try wait on the semaphore (non-blocking)

Description
This function checks if the semaphore counter is greater than 0, in which case the counter is decremented.
Returns
'true' if the semaphore was taken and 'false' if not taken (would BLOCK).
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 181 of file qxk_sema.cpp.

◆ signal()

bool QP::QXSemaphore::signal ( )
noexcept

Signal (unblock) the semaphore

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.
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 222 of file qxk_sema.cpp.

Member Data Documentation

◆ m_waitSet

QPSet QP::QXSemaphore::m_waitSet
private

Set of extended threads waiting on this semaphore

Definition at line 144 of file qxk.hpp.

◆ m_count

std::uint8_t QP::QXSemaphore::m_count
private

Semaphore up-down counter

Definition at line 145 of file qxk.hpp.

◆ m_max_count

std::uint8_t QP::QXSemaphore::m_max_count
private

Maximum value of the semaphore counter (e.g., 1 for binary semaphore)

Definition at line 146 of file qxk.hpp.


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