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

#include <qxthread.hpp>

Inheritance diagram for QXThread:
Inheritance graph
Collaboration diagram for QXThread:
Collaboration graph

Public Member Functions

 QXThread (QXThreadHandler const handler, std::uint_fast8_t const tickRate=0U) noexcept
 public constructor More...
 
bool delayCancel (void) noexcept
 cancel the delay More...
 
void init (void const *const e, std::uint_fast8_t const qs_id) noexcept override
 Executes the top-most initial transition in HSM. More...
 
void init (std::uint_fast8_t const qs_id) noexcept override
 overloaded init(qs_id) More...
 
void dispatch (QEvt const *const e, std::uint_fast8_t const qs_id) noexcept override
 Dispatches an event to HSM. 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
 
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
 
void postLIFO (QEvt const *const e) noexcept override
 
- Public Member Functions inherited from QActive
void stop (void)
 
void unsubscribeAll (void) const noexcept
 Un-subscribes from the delivery of all signals to the 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
 Un-subscribes from the delivery of signal sig 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 (void) const noexcept
 Get the priority of the active object. More...
 
void setPrio (std::uint_fast8_t const prio)
 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...
 
QEvt const * get_ (void) noexcept
 Get an event from the event queue of an active object. More...
 
- Public Member Functions inherited from QHsm
virtual ~QHsm ()
 virtual destructor More...
 
bool isIn (QStateHandler const s) noexcept
 
QStateHandler state (void) const noexcept
 
QStateHandler childState (QStateHandler const parent) noexcept
 

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
 obtain a message from the private message queue (block if no messages) More...
 
- Static Public Member Functions inherited from QHsm
static QState top (void *const me, QEvt const *const e) noexcept
 the top-state. More...
 

Private Member Functions

void block_ (void) const noexcept
 
void unblock_ (void) const noexcept
 
void teArm_ (enum_t const sig, std::uint_fast16_t const nTicks) noexcept
 
bool teDisarm_ (void) noexcept
 

Private Attributes

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

Friends

class QXSemaphore
 
class QXMutex
 

Additional Inherited Members

- Data Fields inherited from QActive
std::uint8_t m_prio
 QF priority (1..QF_MAX_ACTIVE) of this active object. More...
 
- Static Public Attributes inherited from QHsm
static constexpr QState Q_RET_SUPER {static_cast<QState>(0)}
 event passed to the superstate to handle More...
 
static constexpr QState Q_RET_SUPER_SUB {static_cast<QState>(1)}
 event passed to submachine superstate More...
 
static constexpr QState Q_RET_UNHANDLED {static_cast<QState>(2)}
 event unhandled due to a guard evaluating to 'false' More...
 
static constexpr QState Q_RET_HANDLED {static_cast<QState>(3)}
 event handled (internal transition) More...
 
static constexpr QState Q_RET_IGNORED {static_cast<QState>(4)}
 event silently ignored (bubbled up to top) More...
 
static constexpr QState Q_RET_ENTRY {static_cast<QState>(5)}
 state entry action executed More...
 
static constexpr QState Q_RET_EXIT {static_cast<QState>(6)}
 state exit action executed More...
 
static constexpr QState Q_RET_NULL {static_cast<QState>(7)}
 return value without any effect More...
 
static constexpr QState Q_RET_TRAN {static_cast<QState>(8)}
 regular transition taken More...
 
static constexpr QState Q_RET_TRAN_INIT {static_cast<QState>(9)}
 initial transition taken More...
 
static constexpr QState Q_RET_TRAN_EP {static_cast<QState>(10)}
 entry-point transition into a submachine More...
 
static constexpr QState Q_RET_TRAN_HIST {static_cast<QState>(11)}
 transition to history of a given state More...
 
static constexpr QState Q_RET_TRAN_XP {static_cast<QState>(12)}
 exit-point transition out of a submachine More...
 
- Protected Types inherited from QHsm
enum  ReservedHsmSignals : QSignal { Q_ENTRY_SIG = 1 , Q_EXIT_SIG , Q_INIT_SIG }
 
- 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
 
QState qm_tran_hist (QMState const *const hist, void const *const tatbl) noexcept
 
QState qm_tran_init (void const *const tatbl) noexcept
 
QState qm_tran_ep (void const *const tatbl) noexcept
 
QState qm_tran_xp (QActionHandler const xp, void const *const tatbl) noexcept
 
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...
 
virtual QStateHandler getStateHandler () noexcept
 Get the current state handler of the HSM. 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
 

Detailed Description

Extended (blocking) thread of the QXK preemptive kernel

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 thred-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 (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
uint32_t stack_blinky[80]; // stack for the thread
int main() {
. . .
// initialize and start blinky thread
blinky.start(5U, // priority
(void *)0, 0, // message queue (not used)
stack_blinky, sizeof(stack_blinky), // stack
nullptr); // initialization event
. . .
return QP::QF::run(); // run the application
}
unsigned long int uint32_t
Definition: 16bit/stdint.h:31
static int_t run(void)
Transfers control to QF to run the application.
Definition: qk.cpp:137
static bool delay(std::uint_fast16_t const nTicks) noexcept
delay (block) the current extended thread for a specified # ticks
Definition: qxk_xthr.cpp:549

Definition at line 66 of file qxthread.hpp.

Constructor & Destructor Documentation

◆ QXThread()

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

public constructor

Definition at line 73 of file qxk_xthr.cpp.

Member Function Documentation

◆ delay()

bool delay ( std::uint_fast16_t const  nTicks)
staticnoexcept

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

delay (timed blocking of) the current extended thread (static)

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

◆ delayCancel()

bool delayCancel ( void  )
noexcept

cancel the delay

Definition at line 586 of file qxk_xthr.cpp.

◆ queueGet()

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

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 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 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 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 already blocked on any object.
also: the thread must NOT be holding a scheduler lock.

Definition at line 366 of file qxk_xthr.cpp.

◆ init() [1/2]

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

Executes the top-most initial transition in HSM.

Reimplemented from QHsm.

Definition at line 84 of file qxk_xthr.cpp.

◆ init() [2/2]

void init ( std::uint_fast8_t const  qs_id)
inlineoverridevirtualnoexcept

overloaded init(qs_id)

Reimplemented from QHsm.

Definition at line 87 of file qxthread.hpp.

◆ dispatch()

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

Dispatches an event to HSM.

Reimplemented from QHsm.

Definition at line 93 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 the thread with the framework.

Description
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() {
static QP::QEvt const *tableQueueSto[N_PHILO];
static QP::QEvt const *philoQueueSto[N_PHILO][N_PHILO];
. . .
// stacks and queues for the extended test threads
static QP::QEvt const *test1QueueSto[5];
static uint64_t test1StackSto[64];
static QP::QEvt const *test2QueueSto[5];
static uint64_t test2StackSto[64];
QP::QF::init(); // initialize the framework and the underlying RT kernel
BSP::init(); // initialize the BSP
. . .
// start the extended Test1 thread
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]
. . .
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
}
unsigned long long uint64_t
Definition: 16bit/stdint.h:32
static void init(void)
QF initialization.
Definition: qk.cpp:78
#define Q_DIM(array_)
Definition: qassert.h:337
QP/C++ public interface including backwards-compatibility layer.
Precondition
this function must:

Reimplemented from QActive.

Definition at line 122 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

Overloaded start function (no initialization event)

Reimplemented from QActive.

Definition at line 103 of file qxthread.hpp.

◆ post_()

bool post_ ( QEvt const *const  e,
std::uint_fast16_t const  margin,
void const *const  sender 
)
overridevirtualnoexcept
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]epointer to the event to be posted
[in]marginnumber of required free slots in the queue after posting the event. The special value QP::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 QP::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. delivered in this case.
Precondition
event pointer must be valid

Reimplemented from QActive.

Definition at line 200 of file qxk_xthr.cpp.

◆ postLIFO()

void postLIFO ( QEvt const *const  e)
overridevirtualnoexcept

Posts an event directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy.

Description
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
QActive::postLIFO_()

Reimplemented from QActive.

Definition at line 341 of file qxk_xthr.cpp.

◆ block_()

void block_ ( void  ) const
privatenoexcept
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 459 of file qxk_xthr.cpp.

◆ unblock_()

void unblock_ ( void  ) const
privatenoexcept
Description
Intenral implementation of un-blocking the given extended thread.
Note
must be called from within a critical section

Definition at line 473 of file qxk_xthr.cpp.

◆ teArm_()

void teArm_ ( enum_t const  sig,
std::uint_fast16_t const  nTicks 
)
privatenoexcept
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 491 of file qxk_xthr.cpp.

◆ teDisarm_()

bool teDisarm_ ( void  )
privatenoexcept
Description
Intenral implementation of disarming the private time event.
Note
Must be called from within a critical section

Definition at line 532 of file qxk_xthr.cpp.

Friends And Related Function Documentation

◆ QXSemaphore

friend class QXSemaphore
friend

Definition at line 134 of file qxthread.hpp.

◆ QXMutex

friend class QXMutex
friend

Definition at line 135 of file qxthread.hpp.

Field Documentation

◆ m_timeEvt

QTimeEvt m_timeEvt
private

time event to handle blocking timeouts

Definition at line 131 of file qxthread.hpp.


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