QP::QXSemaphore Class Reference

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

Public Member Functions
void	init (std::uint_fast8_t const count, std::uint_fast8_t const max_count=0xFFU) noexcept
	Initialize the counting semaphore.
bool	wait (QTimeEvtCtr const nTicks=QXTHREAD_NO_TIMEOUT) noexcept
	Wait (block) on the semaphore.
bool	tryWait () noexcept
	Try wait on the semaphore (non-blocking).
bool	signal () noexcept
	Signal (unblock) the semaphore.

Private Attributes
QPSet	m_waitSet
	Set of extended threads waiting on this semaphore .
std::uint8_t	m_count
	Semaphore up-down counter .
std::uint8_t	m_max_count
	Maximum value of the semaphore counter (1 for binary semaphore) .

Friends
class	QS

Detailed Description

Counting Semaphore of the QXK preemptive kernel.

Details

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();
        . . .
   }
}

Definition at line 140 of file qxk.hpp.

Constructor & Destructor Documentation

QXSemaphore()

QP::QXSemaphore::QXSemaphore ( )

noexcept

Definition at line 52 of file qxk_sema.cpp.

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.

Details

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]	count	initial value of the semaphore counter
[in]	max_count	maximum 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).

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();
        . . .
   }
}

Definition at line 58 of file qxk_sema.cpp.

wait()

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

noexcept

Wait (block) on the semaphore.

Details

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]

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.

Return values

true	If the semaphore has been taken
false	If a timeout occurred.

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.

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

tryWait()

bool QP::QXSemaphore::tryWait ( )

noexcept

Try wait on the semaphore (non-blocking).

Details

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

Return values

true	If the semaphore was taken
false	If the semaphore was NOT taken (would BLOCK).

Note

This function can be called from any context, including ISRs and basic threads (active objects).

Definition at line 158 of file qxk_sema.cpp.

signal()

bool QP::QXSemaphore::signal ( )

noexcept

Signal (unblock) the semaphore.

Details

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.

Return values

true	When the semaphore signaled
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.

Definition at line 192 of file qxk_sema.cpp.

Friends And Related Symbol Documentation

QS

friend class QS

friend

Definition at line 156 of file qxk.hpp.

Member Data Documentation

m_waitSet

QPSet QP::QXSemaphore::m_waitSet

private

Set of extended threads waiting on this semaphore .

Definition at line 151 of file qxk.hpp.

m_count

std::uint8_t QP::QXSemaphore::m_count

private

Semaphore up-down counter .

Definition at line 152 of file qxk.hpp.

m_max_count

std::uint8_t QP::QXSemaphore::m_max_count

private

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

Definition at line 153 of file qxk.hpp.