QP/C  5.9.7
qxk_sema.c File Reference

QXK preemptive kernel semaphore functions. 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 QXSemaphore_init (QXSemaphore *const me, uint_fast16_t count, uint_fast16_t max_count)
 initialize the counting semaphore More...
 
bool QXSemaphore_wait (QXSemaphore *const me, uint_fast16_t const nTicks)
 wait (block) on the semaphore More...
 
bool QXSemaphore_tryWait (QXSemaphore *const me)
 try wait on the semaphore (non-blocking) More...
 
bool QXSemaphore_signal (QXSemaphore *const me)
 signal (unblock) the semaphore More...
 

Detailed Description

QXK preemptive kernel semaphore functions.

Definition in file qxk_sema.c.

Function Documentation

◆ QXSemaphore_init()

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

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,out]mepointer (see Object Orientation)
[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 78 of file qxk_sema.c.

◆ QXSemaphore_wait()

bool QXSemaphore_wait ( QXSemaphore *const  me,
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.
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.
[in]tickRatesystem clock tick rate serviced in this call.
Returns
'true' if the semaphore has been signaled and 'false' if a timeout occured.
Note
Multiple extended threads can wait for a given semahpre.
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 holding a scheduler lock;
  • the thread must NOT be already blocked on any object.

Definition at line 113 of file qxk_sema.c.

◆ QXSemaphore_tryWait()

bool QXSemaphore_tryWait ( QXSemaphore *const  me)

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.
Parameters
[in,out]mepointer (see Object Orientation)
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 threds (active objects).
Precondition
the semaphore must be initialized

Definition at line 173 of file qxk_sema.c.

◆ QXSemaphore_signal()

bool QXSemaphore_signal ( QXSemaphore *const  me)

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]mepointer (see Object Orientation)
Returns
'true' when the semaphore 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 214 of file qxk_sema.c.