QP/C  5.9.7
qxk_xthr.c File Reference

QXK preemptive kernel extended (blocking) thread 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

static void QXThread_init_ (QMsm *const me, QEvt const *const e)
 
static void QXThread_dispatch_ (QMsm *const me, QEvt const *const e)
 
static void QXThread_start_ (QActive *const me, uint_fast8_t prio, QEvt const *qSto[], uint_fast16_t qLen, void *stkSto, uint_fast16_t stkSize, QEvt const *ie)
 
static bool QXThread_post_ (QActive *const me, QEvt const *const e, uint_fast16_t const margin, void const *const sender)
 
static void QXThread_postLIFO_ (QActive *const me, QEvt const *const e)
 
void QXThread_ctor (QXThread *const me, QXThreadHandler handler, uint_fast8_t tickRate)
 constructor of an extended-thread More...
 
QEvt const * QXThread_queueGet (uint_fast16_t const nTicks)
 obtain a message from the private message queue (block if no messages) More...
 
void QXThread_block_ (QXThread const *const me)
 internal functin to block (suspend) a given extended thread More...
 
void QXThread_unblock_ (QXThread const *const me)
 internal function to unblock (resume) a given extended thread. More...
 
void QXThread_teArm_ (QXThread *const me, QSignal sig, uint_fast16_t const nTicks)
 internal function to arm the private time event for a given thread. More...
 
bool QXThread_teDisarm_ (QXThread *const me)
 internal function to disarm the private time event for a given thread. More...
 
bool QXThread_delay (uint_fast16_t const nTicks)
 delay (timed block) the current extended thread (static, no me-pointer) More...
 
bool QXThread_delayCancel (QXThread *const me)
 cancel the delay
 
void QXK_threadRet_ (void)
 called when a thread function returns More...
 

Detailed Description

QXK preemptive kernel extended (blocking) thread functions.

Definition in file qxk_xthr.c.

Function Documentation

◆ QXThread_start_()

static void QXThread_start_ ( QActive *const  me,
uint_fast8_t  prio,
QEvt const *  qSto[],
uint_fast16_t  qLen,
void *  stkSto,
uint_fast16_t  stkSize,
QEvt const *  ie 
)
static
Description
Starts execution of the extended thread and registers it with the framework. The extended thread becomes ready-to-run immediately and is scheduled if the QXK is already running.
Parameters
[in,out]mepointer (see Object Orientation)
[in]priopriority at which to start the extended thread
[in]qStopointer to the storage for the ring buffer of the event queue. This cold be NULL, if this extended thread does not use the built-in event queue.
[in]qLenlength of the event queue [in events], or zero if queue not used
[in]stkStopointer to the stack storage (must be provided)
[in]stkSizestack size [in bytes] (must not be zero)
[in]iepointer to the initial event (not used).
Note
This function should be called via the macro QXTHREAD_START().
Usage
The following example shows starting an extended thread:
Precondition
this function must:
  • NOT be called from an ISR;
  • the thread priority cannot exceed QF_MAX_ACTIVE;
  • the stack storage must be provided;
  • the thread object must be instantiated (see QXThread_ctor()).

Definition at line 149 of file qxk_xthr.c.

◆ QXThread_post_()

static bool QXThread_post_ ( QActive *const  me,
QEvt const *const  e,
uint_fast16_t const  margin,
void const *const  sender 
)
static
Description
Direct event posting is the simplest asynchronous communication method available in QF. The following example illustrates how the Philo active object posts directly the HUNGRY event to the Table active object.

The parameter margin specifies the minimum number of free slots in the queue that must be available for posting to succeed. The function returns 1 (success) if the posting succeeded (with the provided margin) and 0 (failure) when the posting fails.
Parameters
[in,out]mepointer (see Object Orientation)
[in]epointer to the event to be posted
[in]marginnumber of required free slots in the queue after posting the event.
Note
this function should be called only via the macro QXTHREAD_POST_X().
The zero value of the margin parameter is special and denotes situation when the post() operation is assumed to succeed (event delivery guarantee). An assertion fires, when the event cannot be delivered in this case.
For compatibility with the V-table from the superclass QActive, the me-pointer is typed as pointing to QActive. However, the me pointer here actually points to the QXThread subclass. Therefore the downcast (QXThread *)me is always correct.
Precondition
event pointer must be valid
Note
assert if event cannot be posted and dropping events is not acceptable

Definition at line 231 of file qxk_xthr.c.

◆ QXThread_postLIFO_()

static void QXThread_postLIFO_ ( QActive *const  me,
QEvt const *const  e 
)
static
Description
Last-In-First-Out (LIFO) policy is not supported for extened threads.
Parameters
[in]mepointer (see Object Orientation)

Definition at line 357 of file qxk_xthr.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_queueGet()

QEvt const* QXThread_queueGet ( uint_fast16_t const  nTicks)

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.
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.
Precondition
this function must:
  • NOT be called from an ISR;
  • 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 383 of file qxk_xthr.c.

◆ QXThread_block_()

void QXThread_block_ ( QXThread const *const  me)

internal functin to block (suspend) a given extended thread

Description
Intenral implementation of blocking the given extended thread.
Note
must be called from within a critical section
Precondition
the thread holding the lock cannot block!

Definition at line 479 of file qxk_xthr.c.

◆ QXThread_unblock_()

void QXThread_unblock_ ( QXThread const *const  me)

internal function to unblock (resume) a given extended thread.

Description
Intenral implementation of un-blocking the given extended thread.
Note
must be called from within a critical section

Definition at line 495 of file qxk_xthr.c.

◆ QXThread_teArm_()

void QXThread_teArm_ ( QXThread *const  me,
QSignal  sig,
uint_fast16_t const  nTicks 
)

internal function to arm the private time event for a given thread.

Description
Intenral implementation of arming the private time event for a given timeout at a given system tick rate.
Note
must be called from within a critical section
Precondition
the time event must be unused

Definition at line 513 of file qxk_xthr.c.

◆ QXThread_teDisarm_()

bool QXThread_teDisarm_ ( QXThread *const  me)

internal function to disarm the private time event for a given thread.

Description
Intenral implementation of disarming the private time event.
Note
must be called from within a critical section

Definition at line 555 of file qxk_xthr.c.

◆ QXThread_delay()

bool QXThread_delay ( uint_fast16_t const  nTicks)

delay (timed block) the current extended thread (static, no me-pointer)

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

Precondition
this function must:
  • NOT be called from an ISR;
  • be called from an extended thread;
  • the thread must NOT be holding a scheduler lock and;
  • the thread must NOT be already blocked on any object.

Definition at line 571 of file qxk_xthr.c.

◆ QXK_threadRet_()

void QXK_threadRet_ ( void  )

called when a thread function returns

Description
Called when the extended-thread handler function returns.
Note
Most thread handler functions are structured as endless loops that never return. But it is also possible to structure threads as one-shot functions that perform their job and return. In that case this function peforms cleanup after the thread.

Definition at line 639 of file qxk_xthr.c.