QP/C  5.8.2
qxthread.h File Reference

QXK/C eXtended (blocking) thread. More...

Go to the source code of this file.

Data Structures

struct  QXThread
 eXtended (blocking) thread of the QXK preemptive kernel More...
 
struct  QXSemaphore
 Counting Semaphore of the QXK preemptive kernel. More...
 

Macros

#define QXTHREAD_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, param_)
 Polymorphically start an extended thread. More...
 
#define QXTHREAD_POST_X(me_, e_, margin_, sender_)   QACTIVE_POST_X(&(me_)->super, (e_), (margin_), (sender_))
 
#define QXTHREAD_NO_TIMEOUT   ((uint_fast16_t)0)
 no-timeout special timeout value when blocking on queues or semaphores
 
#define Q_XTHREAD_CAST(handler_)   ((QXThreadHandler)(handler_))
 Perform cast to QXThreadHandler. More...
 

Typedefs

typedef QActiveVtbl QXThreadVtbl
 Virtual Table for the QXThread class (inherited from QActiveVtbl) More...
 
typedef void(* QXThreadHandler) (QXThread *const me)
 Thread handler pointer-to-function.
 

Functions

void QXThread_ctor (QXThread *const me, QXThreadHandler handler, uint_fast8_t tickRate)
 constructor of an extended-thread More...
 
bool QXThread_delay (uint_fast16_t const nTicks, uint_fast8_t const tickRate)
 delay (block) the current extended thread for a specified # ticks More...
 
bool QXThread_delayCancel (QXThread *const me)
 cancel the delay
 
QEvt const * QXThread_queueGet (uint_fast16_t const nTicks, uint_fast8_t const tickRate)
 obtain a message from the private message queue (block if no messages) More...
 
void QXSemaphore_init (QXSemaphore *const me, uint_fast16_t count)
 initialize the counting semaphore More...
 
void QXSemaphore_signal (QXSemaphore *const me)
 signal (unblock) the semaphore More...
 
bool QXSemaphore_wait (QXSemaphore *const me, uint_fast16_t const nTicks, uint_fast8_t const tickRate)
 wait (block) on the semaphore More...
 

Detailed Description

QXK/C eXtended (blocking) thread.

Definition in file qxthread.h.


Data Structure Documentation

◆ QXThread

struct QXThread

eXtended (blocking) thread of the QXK preemptive kernel

Description
QXThread represents the eXtended (blocking) thread of the QXK preemptive kernel. Each extended thread in the application must be represented by the corresponding QXThread instance
Note
Typically, QXThread is instantiated directly in the application code. The customization of the thread occurs in the QXThread_ctor(), where you provide the thred-handler function as the parameter.
See also
QActive
Usage
The following example illustrates how to instantiate an extended thread in your application.

Definition at line 63 of file qxthread.h.

Data Fields
QActive super
QTimeEvt timeEvt

◆ QXSemaphore

struct QXSemaphore

Counting Semaphore of the QXK preemptive kernel.

Definition at line 159 of file qxthread.h.

Data Fields
uint_fast16_t count
QPSet waitSet set of extended-threads waiting on this semaphore

Macro Definition Documentation

◆ Q_XTHREAD_CAST

#define Q_XTHREAD_CAST (   handler_)    ((QXThreadHandler)(handler_))

Perform cast to QXThreadHandler.

Description
This macro encapsulates the cast of a specific thread handler function pointer to QXThreadHandler, which violates MISRA-C 2004 rule 11.4(adv). This macro helps to localize this deviation.

Definition at line 155 of file qxthread.h.

◆ QXTHREAD_POST_X

#define QXTHREAD_POST_X (   me_,
  e_,
  margin_,
  sender_ 
)    QACTIVE_POST_X(&(me_)->super, (e_), (margin_), (sender_))
Description
This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.
Parameters
[in,out]me_pointer (see Object Orientation)
[in]e_pointer to the event to post
[in]margin_the minimum free slots in the queue, which must still be available after posting the event
[in]sender_pointer to the sender object.
Returns
'true' if the posting succeeded, and 'false' if the posting failed due to insufficient margin of free slots available in the queue.
Note
The sender_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the QACTIVE_POST() macro does not pass the sender_ argument, so the overhead of passing this extra argument is entirely avoided.
the pointer to the sender object is not necessarily a pointer to an active object. In fact, if QACTIVE_POST() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.
Usage
extern QActive *AO_Table;
. . .
/* typically inside a state machine action */
TableEvt *pe;
Q_NEW_X(pe, TableEvt, 5U, HUNGRY_SIG); /* dynamic alloc, margin==5 */
if (pe != (TableEvt *)0) {
pe->philNum = me->num;
QACTIVE_POST_X(AO_Table, &pe->super, 3U, me); /* margin==3 */
}
. . .

Definition at line 132 of file qxthread.h.

◆ QXTHREAD_START

#define QXTHREAD_START (   me_,
  prio_,
  qSto_,
  qLen_,
  stkSto_,
  stkLen_,
  param_ 
)
Value:
QACTIVE_START((me_), (prio_), (QEvt const **)(qSto_), (qLen_), \
(stkSto_), (stkLen_), (param_))
Event structure.
Definition: qep.h:153
#define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, param_)
Polymorphically start an active object.
Definition: qf.h:206

Polymorphically start an extended thread.

Description
Starts execution of the thread and registers the thread with the framework.
Parameters
[in,out]me_pointer (see Object Orientation)
[in]prio_priority of the extended-thread
[in]qSto_pointer to the storage for the ring buffer of the message queue (possibly NULL)
[in]qLen_length of the message queue [events] (possibly 0)
[in]stkSto_pointer to the stack storage (required)
[in]stkSize_stack size [bytes]
[in]param_pointer to the additional port-specific parameter(s) (might be NULL).
Usage
int main() {
. . .
/* stack for the QXK's idle thread */
static uint64_t idleStackSto[32];
Test_ctor(); /* instantiate the Test "naked" thread */
QF_init(); /* initialize the framework */
BSP_init(); /* initialize the Board Support Package */
/* initialize QXK... */
QXK_init(idleStackSto, sizeof(idleStackSto));
/* initialize publish-subscribe... */
QF_psInit(subscrSto, Q_DIM(subscrSto));
/* initialize event pools... */
QF_poolInit(smlPoolSto, sizeof(smlPoolSto), sizeof(smlPoolSto[0]));
/* start the active objects... */
QACTIVE_START(AO_Table, /* AO to start */
(uint_fast8_t)(N_PHILO + 2), /* QP priority of the AO */
tableQueueSto, /* event queue storage */
Q_DIM(tableQueueSto), /* queue length [events] */
tableStackSto, /* stack storage */
sizeof(tableStackSto), /* stack size [bytes] */
(QEvt *)0); /* initialization event */
. . .
/* start the "naked" thread */
QXTHREAD_START(&XT_Test->super, /* Thread to start */
(uint_fast8_t)10U, /* QP priority of the thread */
testQueueSto, /* message queue storage */
Q_DIM(testQueueSto), /* message length [events] */
testStackSto, /* stack storage */
sizeof(testStackSto), /* stack size [bytes] */
(QEvt *)0); /* initialization event */
return QF_run(); /* run the QF application */
}

Definition at line 93 of file qxthread.h.

Typedef Documentation

◆ QXThreadVtbl

Virtual Table for the QXThread class (inherited from QActiveVtbl)

Note
QXThread inherits QActive without adding any new virtual functions and therefore, QXThreadVtbl is typedef'ed as QActiveVtbl.

Definition at line 74 of file qxthread.h.

Function Documentation

◆ QXSemaphore_init()

void QXSemaphore_init ( QXSemaphore *const  me,
uint_fast16_t  count 
)

initialize the counting semaphore

Description
Initializes a semaphore with the specified count. If the semaphore is used for resource sharing, the initial value of the semaphore 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.
Parameters
[in,out]mepointer (see Object Orientation)
[in]countinitial value of the semaphore counter
Note
QXSemaphore_init() must be called before the semaphore can be used (signaled or waited on).

Definition at line 73 of file qxk_sema.c.

◆ QXSemaphore_signal()

void 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)
Note
A semaphore can be signaled from many places, including from ISRs, basic threads (AOs), and extended threads.

Definition at line 157 of file qxk_sema.c.

◆ QXSemaphore_wait()

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

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 the timeout occured.
Note
Multiple extended threads can wait for a given semahpre.

Definition at line 103 of file qxk_sema.c.

◆ QXThread_ctor()

void QXThread_ctor ( QXThread *const  me,
QXThreadHandler  handler,
uint_fast8_t  tickRate 
)

constructor of an extended-thread

Description
Performs the first step of QXThread initialization by assigning the thread-handler function and the tick rate at which it will handle the timeouts.
Parameters
[in,out]mepointer (see Object Orientation)
[in]handlerthe thread-handler function
Note
Must be called only ONCE before QXTHREAD_START().
Usage
The following example illustrates how to invoke QXThread_ctor() in the main() function

Definition at line 91 of file qxk_xthr.c.

◆ QXThread_delay()

bool QXThread_delay ( uint_fast16_t const  nTicks,
uint_fast8_t const  tickRate 
)

delay (block) the current extended thread for a specified # ticks

delay (block) the current extended thread for a specified # ticks

Definition at line 557 of file qxk_xthr.c.

◆ QXThread_queueGet()

QEvt const* QXThread_queueGet ( uint_fast16_t const  nTicks,
uint_fast8_t const  tickRate 
)

obtain a message from the private message queue (block if no messages)

Description
The QXThread_queueGet() operation allows the calling extended thread to receive QP events directly into its own built-in event queue from an ISR, basic thread (AO), or another extended thread.

If QXThread_queueGet() is called when no events are present in the threadís event queue, the operation blocks the current extended thread until either an event is received, or a user-specified timeout expires.

Parameters
[in]nTicksnumber of clock ticks (at the associated rate) to wait for the event to arrive. The value of QXTHREAD_NO_TIMEOUT indicates that no timeout will occur and the queue will block indefinitely.
[in]tickRatesystem clock tick rate serviced in this call.
Returns
Returns pointer to the event. If the pointer is not NULL, the event was delivered. Otherwise the event pointer of NULL indicates that the queue has timed out.

Definition at line 377 of file qxk_xthr.c.