QP/C++  7.0.1
Real-Time Embedded Framework
QXThread Class Reference

Extended (blocking) thread of the QXK preemptive kernel. More...

#include <qxk.hpp>

Inheritance diagram for QXThread:
QActive QHsm

Public Member Functions

 QXThread (QXThreadHandler const handler, std::uint_fast8_t const tickRate=0U) noexcept
 public constructor More...
 
bool delayCancel () noexcept
 cancel the delay More...
 
void init (void const *const e, std::uint_fast8_t const qs_id) override
 Overrides QHsm::init() More...
 
void init (std::uint_fast8_t const qs_id) override
 Overrides QHsm::init() More...
 
void dispatch (QEvt const *const e, std::uint_fast8_t const qs_id) override
 Overrides QHsm::dispatch() More...
 
void start (std::uint_fast8_t const prio, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize, void const *const par) override
 Starts execution of an extended thread and registers the thread with the framework. More...
 
void start (std::uint_fast8_t const prio, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize) override
 Overloaded start function (no initialization event) More...
 
bool post_ (QEvt const *const e, std::uint_fast16_t const margin, void const *const sender) noexcept override
 Posts an event e directly to the event queue of the extended thread using the First-In-First-Out (FIFO) policy. More...
 
void postLIFO (QEvt const *const e) noexcept override
 Posts an event directly to the event queue of the extended thread using the Last-In-First-Out (LIFO) policy. More...
 
- Public Member Functions inherited from QActive
virtual void start (std::uint_fast8_t const prio, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize, void const *const par)
 Starts execution of an active object and registers the object with the framework. More...
 
virtual void start (std::uint_fast8_t const prio, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize)
 Overloaded start function (no initialization parameter) More...
 
void stop ()
 Stops execution of an active object and removes it from the framework's supervision. More...
 
virtual bool post_ (QEvt const *const e, std::uint_fast16_t const margin, void const *const sender) noexcept
 Posts an event e directly to the event queue of the active object using the First-In-First-Out (FIFO) policy. More...
 
virtual void postLIFO (QEvt const *const e) noexcept
 Posts an event e directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy. More...
 
QEvt const * get_ () noexcept
 Get an event from the event queue of an active object. More...
 
void subscribe (enum_t const sig) const noexcept
 Subscribes for delivery of signal sig to the active object. More...
 
void unsubscribe (enum_t const sig) const noexcept
 Unsubscribes from the delivery of signal sig to the active object. More...
 
void unsubscribeAll () const noexcept
 Unsubscribes from the delivery of all signals to the active object. More...
 
bool defer (QEQueue *const eq, QEvt const *const e) const noexcept
 Defer an event to a given separate event queue. More...
 
bool recall (QEQueue *const eq) noexcept
 Recall a deferred event from a given event queue. More...
 
std::uint_fast16_t flushDeferred (QEQueue *const eq) const noexcept
 Flush the specified deferred queue 'eq'. More...
 
std::uint_fast8_t getPrio () const noexcept
 Get the priority of the active object. More...
 
void setPrio (std::uint_fast8_t const prio) noexcept
 Set the priority of the active object. More...
 
void setAttr (std::uint32_t attr1, void const *attr2=nullptr)
 Generic setting of additional attributes (useful in QP ports) More...
 
void register_ () noexcept
 Register this active object to be managed by the framework. More...
 
void unregister_ () noexcept
 Un-register the active object from the framework. More...
 
- Public Member Functions inherited from QHsm
virtual void init (void const *const e, std::uint_fast8_t const qs_id)
 Executes the top-most initial transition in QP::QHsm. More...
 
virtual void init (std::uint_fast8_t const qs_id)
 overloaded init(qs_id) More...
 
virtual void dispatch (QEvt const *const e, std::uint_fast8_t const qs_id)
 Dispatches an event to QP::QHsm. More...
 
QStateHandler state () const noexcept
 Obtain the current state (state handler function) More...
 
virtual QStateHandler getStateHandler () noexcept
 Get the current state handler of the QP::QHsm. More...
 
bool isIn (QStateHandler const s) noexcept
 Tests if a given state is part of the current active state configuration. More...
 
QStateHandler childState (QStateHandler const parent) noexcept
 Obtain the current active child state of a given parent. More...
 

Static Public Member Functions

static bool delay (std::uint_fast16_t const nTicks) noexcept
 delay (block) the current extended thread for a specified # ticks More...
 
static QEvt const * queueGet (std::uint_fast16_t const nTicks=QXTHREAD_NO_TIMEOUT) noexcept
 Get a message from the private message queue (block if no messages) More...
 
- Static Public Member Functions inherited from QActive
static void psInit (QSubscrList *const subscrSto, enum_t const maxSignal) noexcept
 Publish-subscribe initialization. More...
 
static void publish_ (QEvt const *const e, void const *const sender, std::uint_fast8_t const qs_id) noexcept
 Publish event to all subscribers of a given signal e->sig More...
 
static void thread_ (QActive *act)
 Thread routine for executing an active object act More...
 
- Static Public Member Functions inherited from QHsm
static QState top (void *const me, QEvt const *const e) noexcept
 The top-state handler. More...
 

Static Public Attributes

static QXThread idle
 the idle thread of the QXK kernel More...
 
- Static Public Attributes inherited from QActive
static QActiveregistry_ [QF_MAX_ACTIVE+1U]
 Internal array of registered active objects. More...
 
static QSubscrListsubscrList_
 pointer to the array of all subscriber AOs for a given event signal More...
 
static enum_t maxPubSignal_
 The maximum published signal (the size of the subscrList_ array) More...
 
- Static Public Attributes inherited from QHsm
static constexpr std::int_fast8_t MAX_NEST_DEPTH_ {6}
 Maximum nesting depth of states in HSM. More...
 

Private Member Functions

void block_ () const noexcept
 Block the extended thread. More...
 
void unblock_ () const noexcept
 Unblock the extended thread. More...
 
void teArm_ (enum_t const sig, std::uint_fast16_t const nTicks) noexcept
 Arm the private time event. More...
 
bool teDisarm_ () noexcept
 Disarm the private time event. More...
 

Private Attributes

QTimeEvt m_timeEvt
 time event to handle blocking timeouts More...
 

Friends

class QXSemaphore
 
class QXMutex
 

Additional Inherited Members

- Public Types inherited from QHsm
enum  ReservedHsmSignals : QSignal { Q_ENTRY_SIG = 1U , Q_EXIT_SIG , Q_INIT_SIG }
 Reserved signals by the HSM-style state machine implementation strategy. More...
 
enum  QStateRet : std::uint_fast8_t {
  Q_RET_SUPER , Q_RET_SUPER_SUB , Q_RET_UNHANDLED , Q_RET_HANDLED ,
  Q_RET_IGNORED , Q_RET_ENTRY , Q_RET_EXIT , Q_RET_NULL ,
  Q_RET_TRAN , Q_RET_TRAN_INIT , Q_RET_TRAN_EP , Q_RET_TRAN_HIST ,
  Q_RET_TRAN_XP
}
 All possible return values from state-handlers. More...
 
- Public Attributes inherited from QActive
std::uint8_t m_prio
 QF priority (1..QF_MAX_ACTIVE) of this active object. More...
 
- Protected Member Functions inherited from QActive
 QActive (QStateHandler const initial) noexcept
 protected constructor (abstract class) More...
 
- Protected Member Functions inherited from QHsm
 QHsm (QStateHandler const initial) noexcept
 protected constructor of QHsm More...
 
QState tran (QStateHandler const target) noexcept
 Helper function to specify a state transition. More...
 
QState tran_hist (QStateHandler const hist) noexcept
 Helper function to specify a transition to history. More...
 
QState super (QStateHandler const superstate) noexcept
 Helper function to specify the superstate of a given state. More...
 
QState qm_tran (void const *const tatbl) noexcept
 Helper function to specify a regular state transition in a QM state-handler. More...
 
QState qm_tran_init (void const *const tatbl) noexcept
 Helper function to specify an initial state transition in a QM state-handler. More...
 
QState qm_tran_hist (QMState const *const hist, void const *const tatbl) noexcept
 Helper function to specifiy a transition to history in a QM state-handler. More...
 
QState qm_tran_ep (void const *const tatbl) noexcept
 Helper function to specify a transition to an entry point to a submachine state in a QM state-handler. More...
 
QState qm_tran_xp (QActionHandler const xp, void const *const tatbl) noexcept
 Helper function to specify a transition to an exit point from a submachine state in a QM state-handler. More...
 
QState qm_entry (QMState const *const s) noexcept
 Helper function to specify a state entry in a QM state-handler. More...
 
QState qm_exit (QMState const *const s) noexcept
 Helper function to specify a state exit in a QM state-handler. More...
 
QState qm_sm_exit (QMState const *const s) noexcept
 Helper function to specify a submachine exit in a QM state-handler. More...
 
QState qm_super_sub (QMState const *const s) noexcept
 Helper function to call in a QM state-handler when it passes the event to the host submachine state to handle an event. More...
 

Detailed Description

QP::QXThread represents the extended (blocking) thread of the QXK kernel. Each blocking thread in the application must be represented by the corresponding QP::QXThread instance

Note
Typically QP::QXThread is instantiated directly in the application code. The customization of the thread occurs in the constructor, where you provide the thread-handler function as the parameter.
See also
QP::QActive
Usage
The following example illustrates how to instantiate and use an extended thread in your application.
void main_blinky(QP::QXThread * const me) { // thread function
while (1) {
for (std::uint32_t volatile i; = 1500U; i != 0U; --i) {
BSP_ledGreenOn();
BSP_ledGreenOff();
}
QP::QXThread::delay(1U); // block for 1 tick
}
}
QP::QXThread blinky(&main_blinky, 0U); // QXK extended-thread object
std::uint32_t stack_blinky[80]; // stack for the thread
int main() {
. . .
// initialize and start Blinky extended thread
blinky.start(5U, // priority
nullptr, 0, // message queue (not used)
stack_blinky, sizeof(stack_blinky), // stack
nullptr); // initialization event
. . .
return QP::QF::run(); // run the application
}
Extended (blocking) thread of the QXK preemptive kernel.
Definition: qxk.hpp:181
static bool delay(std::uint_fast16_t const nTicks) noexcept
delay (block) the current extended thread for a specified # ticks
Definition: qxk_xthr.cpp:93
int_t run()
Transfers control to QF to run the application.
Definition: qk.cpp:180

Definition at line 181 of file qxk.hpp.

Constructor & Destructor Documentation

◆ QXThread()

QXThread ( QXThreadHandler const  handler,
std::uint_fast8_t const  tickRate = 0U 
)
noexcept

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]handlerthe thread-handler function
[in]tickRatethe ticking rate associated with this thread for timeouts in this thread (see QXThread::delay() and TICK_X())
Note
Must be called only ONCE before QXThread::start().

Definition at line 82 of file qxk_xthr.cpp.

Member Function Documentation

◆ delay()

bool delay ( std::uint_fast16_t const  nTicks)
staticnoexcept

Blocking delay for the number of clock tick at the associated tick rate.

Parameters
[in]nTicksnumber of clock ticks (at the associated rate) to wait for the event to arrive.
Returns
'true' if the delay expired and false if it was cancelled by call to QTimeEvt::delayCancel()
Note
For the delay to work, the TICK_X() macro needs to be called periodically at the associated clock tick rate.
See also
QP::QXThread, QTimeEvt::tick_()
Precondition
this function must:
  • NOT be called from an ISR;
  • number of ticks cannot be zero
  • be called from an extended thread;
  • the thread must NOT be already blocked on any object.
also: the thread must NOT be holding a scheduler lock

Definition at line 93 of file qxk_xthr.cpp.

◆ delayCancel()

bool delayCancel ( )
noexcept

Cancel the blocking delay and cause return from the QXThread::delay() function.

Returns
"true" if the thread was actually blocked on QXThread::delay() and "false" otherwise.

Definition at line 131 of file qxk_xthr.cpp.

◆ queueGet()

QEvt const * queueGet ( std::uint_fast16_t const  nTicks = QXTHREAD_NO_TIMEOUT)
staticnoexcept

The QXThread::queueGet() operation allows the calling extended thread to receive QP events (see QP::QEvt) 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 private 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 QP::QXTHREAD_NO_TIMEOUT indicates that no timeout will occur and the queue will block indefinitely.
Returns
A pointer to the event. If the pointer is not nullptr, the event was delivered. Otherwise the event pointer of nullptr 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 already blocked on any object.
also: the thread must NOT be holding a scheduler lock.

Definition at line 149 of file qxk_xthr.cpp.

◆ init() [1/2]

void init ( void const *const  e,
std::uint_fast8_t const  qs_id 
)
overridevirtual

Reimplemented from QHsm.

Definition at line 237 of file qxk_xthr.cpp.

◆ init() [2/2]

void init ( std::uint_fast8_t const  qs_id)
overridevirtual

Reimplemented from QHsm.

Definition at line 247 of file qxk_xthr.cpp.

◆ dispatch()

void dispatch ( QEvt const *const  e,
std::uint_fast8_t const  qs_id 
)
overridevirtual

Reimplemented from QHsm.

Definition at line 253 of file qxk_xthr.cpp.

◆ start() [1/2]

void start ( std::uint_fast8_t const  prio,
QEvt const **const  qSto,
std::uint_fast16_t const  qLen,
void *const  stkSto,
std::uint_fast16_t const  stkSize,
void const *const  par 
)
overridevirtual

Starts execution of an 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]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]parpointer to an extra parameter (might be NULL)
Usage
The following example shows starting an extended thread:
#include "qpcpp.hpp"
. . .
//............................................................................
int main() {
. . .
QP::QF::init(); // initialize the framework and the underlying RT kernel
BSP::init(); // initialize the BSP
. . .
// start the extended threads...
static QP::QEvt const *test1QueueSto[5];
static uint64_t test1StackSto[64];
DPP::XT_Test1->start( // <== start an extended thread
1U, // QP prio of the thread
test1QueueSto, // event queue storage
Q_DIM(test1QueueSto), // queue length [events]
test1StackSto, // stack storage
sizeof(test1StackSto)); // stack size [bytes]
. . .
// start active objects (basic threads)...
static QP::QEvt const *tableQueueSto[N_PHILO];
DPP::AO_Table->start( // <== start a basic thread (AO)
N_PHILO + 7U, // QP priority of the AO
tableQueueSto, // event queue storage
Q_DIM(tableQueueSto), // queue length [events]
nullptr, 0U); // NO stack storage
return QP::QF::run(); // run the QF application
}
Event class.
Definition: qep.hpp:168
void init()
QF initialization.
Definition: qk.cpp:155
#define Q_DIM(array_)
Definition: qassert.h:80
QP/C++ public interface including backwards-compatibility layer.
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 must be instantiated (see QXThread).

Reimplemented from QActive.

Definition at line 263 of file qxk_xthr.cpp.

◆ start() [2/2]

void start ( std::uint_fast8_t const  prio,
QEvt const **const  qSto,
std::uint_fast16_t const  qLen,
void *const  stkSto,
std::uint_fast16_t const  stkSize 
)
inlineoverridevirtual

Reimplemented from QActive.

Definition at line 313 of file qxk.hpp.

◆ post_()

bool post_ ( QEvt const *const  e,
std::uint_fast16_t const  margin,
void const *const  sender 
)
overridevirtualnoexcept

Extended threads can be configured (in QXThread::start()) to have a private event queue. In that case, QP events (see QP::QEvt) can be asynchronously posted or published to the extended thread. The thread can wait (and block) on its queue and then it can process the delivered event.

Parameters
[in]epointer to the event to be posted
[in]marginnumber of required free slots in the queue after posting the event. The special value QF_NO_MARGIN means that this function will assert if posting fails.
[in]senderpointer to a sender object (used in QS only)
Returns
'true' (success) if the posting succeeded (with the provided margin) and 'false' (failure) when the posting fails.
Attention
Should be called only via the macro POST() or POST_X().
Note
The QF_NO_MARGIN 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.
Precondition
event pointer must be valid

Reimplemented from QActive.

Definition at line 312 of file qxk_xthr.cpp.

◆ postLIFO()

void postLIFO ( QEvt const *const  e)
overridevirtualnoexcept

Last-In-First-Out (LIFO) policy is not supported for extened threads.

Parameters
[in]epointer to the event to post to the queue
See also
QXThread::post_(), QActive::postLIFO_()

Reimplemented from QActive.

Definition at line 443 of file qxk_xthr.cpp.

◆ block_()

void block_ ( ) const
privatenoexcept

Internal 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 449 of file qxk_xthr.cpp.

◆ unblock_()

void unblock_ ( ) const
privatenoexcept

Internal implementation of unblocking the given extended thread.

Note
must be called from within a critical section

Definition at line 457 of file qxk_xthr.cpp.

◆ teArm_()

void teArm_ ( enum_t const  sig,
std::uint_fast16_t const  nTicks 
)
privatenoexcept

Internal 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 468 of file qxk_xthr.cpp.

◆ teDisarm_()

bool teDisarm_ ( )
privatenoexcept

Internal implementation of disarming the private time event.

Note
Must be called from within a critical section

Definition at line 510 of file qxk_xthr.cpp.

Friends And Related Function Documentation

◆ QXSemaphore

friend class QXSemaphore
friend

Definition at line 188 of file qxk.hpp.

◆ QXMutex

friend class QXMutex
friend

Definition at line 189 of file qxk.hpp.

Member Data Documentation

◆ m_timeEvt

QTimeEvt m_timeEvt
private

Definition at line 185 of file qxk.hpp.

◆ idle

QXThread idle
static

Definition at line 194 of file qxk.hpp.


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