QP/C++  7.4.0-rc.1
Real-Time Embedded Framework
Loading...
Searching...
No Matches
QP::QXThread Class Reference

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

#include "qxk.hpp"

Inheritance diagram for QP::QXThread:
QP::QActive QP::QAsm

Public Member Functions

 QXThread (QXThreadHandler const handler, std::uint_fast8_t const tickRate=0U) noexcept
 
void init (void const *const e, std::uint_fast8_t const qsId) override
 
void init (std::uint_fast8_t const qsId) override
 
void dispatch (QEvt const *const e, std::uint_fast8_t const qsId) override
 
QTimeEvt const * getTimeEvt () const noexcept
 
bool delayCancel () noexcept
 
- Public Member Functions inherited from QP::QActive
bool isIn (QStateHandler const state) noexcept override
 
QStateHandler childState (QStateHandler const parent) noexcept
 
void setAttr (std::uint32_t attr1, void const *attr2=nullptr)
 
void start (QPrioSpec const prioSpec, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize, void const *const par)
 
void start (QPrioSpec const prioSpec, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize)
 
void stop ()
 
void register_ () noexcept
 
void unregister_ () noexcept
 
bool post_ (QEvt const *const e, std::uint_fast16_t const margin, void const *const sender) noexcept
 
void postLIFO (QEvt const *const e) noexcept
 
QEvt const * get_ () noexcept
 
void subscribe (enum_t const sig) const noexcept
 
void unsubscribe (enum_t const sig) const noexcept
 
void unsubscribeAll () const noexcept
 
bool defer (QEQueue *const eq, QEvt const *const e) const noexcept
 
bool recall (QEQueue *const eq) noexcept
 
std::uint_fast16_t flushDeferred (QEQueue *const eq, std::uint_fast16_t const num=0xFFFFU) const noexcept
 
std::uint_fast8_t getPrio () const noexcept
 
void setPrio (QPrioSpec const prio) noexcept
 
std::uint_fast8_t getPThre () const noexcept
 
QACTIVE_EQUEUE_TYPE const & getEQueue () const noexcept
 
QACTIVE_OS_OBJ_TYPE const & getOsObject () const noexcept
 
QACTIVE_THREAD_TYPE const & getThread () const noexcept
 
void setThread (QACTIVE_THREAD_TYPE const &thr)
 
virtual bool postFromISR (QEvt const *const e, std::uint_fast16_t const margin, void *par, void const *const sender) noexcept
 
- Public Member Functions inherited from QP::QAsm
virtual ~QAsm () noexcept
 
QStateHandler state () const noexcept
 
QMState const * stateObj () const noexcept
 
virtual QStateHandler getStateHandler () noexcept
 

Static Public Member Functions

static bool delay (QTimeEvtCtr const nTicks) noexcept
 
static QEvt const * queueGet (QTimeEvtCtr const nTicks=QXTHREAD_NO_TIMEOUT) noexcept
 
- Static Public Member Functions inherited from QP::QActive
static std::uint_fast16_t getQueueMin (std::uint_fast8_t const prio) noexcept
 
static void psInit (QSubscrList *const subscrSto, enum_t const maxSignal) noexcept
 
static void publish_ (QEvt const *const e, void const *const sender, std::uint_fast8_t const qsId) noexcept
 
static void evtLoop_ (QActive *act)
 
static void publishFromISR (QEvt const *e, void *par, void const *sender) noexcept
 
- Static Public Member Functions inherited from QP::QAsm
static QState top (void *const me, QEvt const *const e) noexcept
 

Static Public Attributes

static constexpr QTimeEvtCtr QXTHREAD_NO_TIMEOUT {0U}
 
- Static Public Attributes inherited from QP::QActive
static QActiveregistry_ [QF_MAX_ACTIVE+1U]
 
static QSubscrListsubscrList_
 
static enum_t maxPubSignal_
 

Private Member Functions

void block_ () const noexcept
 
void unblock_ () const noexcept
 
void teArm_ (enum_t const sig, QTimeEvtCtr const nTicks) noexcept
 
bool teDisarm_ () noexcept
 
void stackInit_ (QP::QXThreadHandler const handler, void *const stkSto, std::uint_fast16_t const stkSize) noexcept
 

Static Private Member Functions

static void timeout_ (QActive *const act)
 

Private Attributes

QTimeEvt m_timeEvt
 

Friends

class QActive
 
class QTimeEvt
 
class QXSemaphore
 
class QXMutex
 

Additional Inherited Members

- Public Types inherited from QP::QAsm
enum  QStateRet : QState {
  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
}
 
enum  ReservedSig : QSignal { Q_EMPTY_SIG , Q_ENTRY_SIG , Q_EXIT_SIG , Q_INIT_SIG }
 Reserved signals by the QP-framework. More...
 
- Public Attributes inherited from QP::QActive
std::uint8_t m_prio_dis
 
std::uint8_t m_pthre_dis
 
- Protected Member Functions inherited from QP::QActive
 QActive (QStateHandler const initial) noexcept
 
- Protected Member Functions inherited from QP::QAsm
 QAsm () noexcept
 
QState tran (QStateHandler const target) noexcept
 
QState tran_hist (QStateHandler const hist) noexcept
 
QState super (QStateHandler const superstate) noexcept
 
QState qm_tran (void const *const tatbl) noexcept
 
QState qm_tran_init (void const *const tatbl) noexcept
 
QState qm_tran_hist (QMState const *const hist, 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
 
QState qm_exit (QMState const *const s) noexcept
 
QState qm_sm_exit (QMState const *const s) noexcept
 
QState qm_super_sub (QMState const *const s) noexcept
 
- Protected Attributes inherited from QP::QActive
std::uint8_t m_prio
 
std::uint8_t m_pthre
 
QACTIVE_THREAD_TYPE m_thread
 
QACTIVE_OS_OBJ_TYPE m_osObject
 
QACTIVE_EQUEUE_TYPE m_eQueue
 
- Protected Attributes inherited from QP::QAsm
QAsmAttr m_state
 
QAsmAttr m_temp
 

Detailed Description

eXtended (blocking) thread of the QXK preemptive kernel

Description
QP::QXThread represents the eXtended (blocking) thread of the QXK kernel. Each extended 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.
Usage
The following example illustrates how to instantiate and use an extended thread in your application.
#include "qpcpp.hpp"
class XThread1 : public QP::QXThread { // <== inherit QP::QXThread
private:
std::uint8_t m_foo;
public:
static XThread1 inst;
XThread1(); // ctor
private:
static void run(QP::QXThread * const thr);
}; // class XThread1
eXtended (blocking) thread of the QXK preemptive kernel
Definition qxk.hpp:88
QP/C++ interface including the backwards-compatibility layer.

Definition at line 88 of file qxk.hpp.

Constructor & Destructor Documentation

◆ QXThread()

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

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]handlerthe thread-handler function
[in]tickRatethe tick rate for timeouts in this thread (see QXThread_delay() and QTIMEEVT_TICK_X())
Note
Must be called only ONCE before QXTHREAD_START().
Usage
The following example illustrates how to invoke QXThread_ctor() in the main() function
#include "qpcpp.hpp"
XThread1::XThread1()
: QXThread(&run) // <===
{}

Definition at line 77 of file qxk_xthr.cpp.

Member Function Documentation

◆ init() [1/2]

void QP::QXThread::init ( void const *const e,
std::uint_fast8_t const qsId )
overridevirtual

Virtual function to take the top-most initial transition in the state machine.

Description
Synchronously executes the top-most initial transition in a state machine (must be overridden in the subclasses).
Parameters
[in]epointer to an initialization parameter (might be nullptr)
[in]qsIdQS-id of this state machine (for QS local filter)
Precondition qep_asm:200
  • the virtual pointer must be initialized,
  • the top-most initial transition must be initialized,
  • the initial transition must not be taken yet.

Reimplemented from QP::QActive.

Definition at line 87 of file qxk_xthr.cpp.

◆ init() [2/2]

void QP::QXThread::init ( std::uint_fast8_t const qsId)
inlineoverridevirtual

Virtual function to take the top-most initial transition in the state machine (overloaded).

Description
Synchronously executes the top-most initial transition in a state machine. This overloaded version takes no initialization parameter.
Parameters
[in]qsIdQS-id of this state machine (for QS local filter)

Reimplemented from QP::QActive.

Definition at line 108 of file qxk.hpp.

◆ dispatch()

void QP::QXThread::dispatch ( QEvt const *const e,
std::uint_fast8_t const qsId )
overridevirtual

Virtual function to dispatch an event to the state machine.

Description
Synchronously dispatches an event for processing to a state machine (must be overridden in the subclasses). The processing of an event represents one run-to-completion (RTC) step.
Parameters
[in]epointer to the event to be dispatched to the MSM
[in]qsIdQS-id of this state machine (for QS local filter)
Precondition qep_asm:302
  • current state must be initialized
  • check the internal integrity (Software Self-Monitoring (SSM))

Reimplemented from QP::QActive.

Definition at line 97 of file qxk_xthr.cpp.

◆ getTimeEvt()

QTimeEvt const * QP::QXThread::getTimeEvt ( ) const
inlinenoexcept

Definition at line 114 of file qxk.hpp.

◆ delay()

bool QP::QXThread::delay ( QTimeEvtCtr const nTicks)
staticnoexcept

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

Description
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 delay has expired, 'false' if it delay was canceled with QXThread::delayCancel().
Precondition qxk_xthr:800
  • 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.
Precondition qxk_xthr:801
  • the thread must NOT be holding a scheduler lock.
Note
For the delay to work, the QTIMEEVT_TICK_X() macro needs to be called periodically at the associated clock tick rate.

Definition at line 107 of file qxk_xthr.cpp.

◆ delayCancel()

bool QP::QXThread::delayCancel ( )
noexcept

Cancel the delay

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

◆ queueGet()

QEvt const * QP::QXThread::queueGet ( QTimeEvtCtr 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 qxk_xthr:500
  • must NOT be called from an ISR;
  • be called from an extended thread;
  • the thread must NOT be already blocked on any object.
Precondition qxk_xthr:501
  • the thread must NOT be holding a scheduler lock.

Definition at line 173 of file qxk_xthr.cpp.

◆ block_()

void QP::QXThread::block_ ( ) const
privatenoexcept

Block QXThread private implementation

Description
Internal implementation of blocking the given extended thread.
Precondition qxk_xthr:600
  • the thread holding the lock cannot block!
Attention
Must be called from within a critical section

Definition at line 270 of file qxk_xthr.cpp.

◆ unblock_()

void QP::QXThread::unblock_ ( ) const
privatenoexcept

Unblock QXThread private implementation

Description
Internal implementation of un-blocking the given extended thread.
Attention
Must be called from within a critical section

Definition at line 284 of file qxk_xthr.cpp.

◆ timeout_()

void QP::QXThread::timeout_ ( QActive *const act)
staticprivate

Process timeout in QXThread (either delay or during blocking)

Parameters
[in,out]actgeneric QActive* pointer of the thread that times out.

Definition at line 300 of file qxk_xthr.cpp.

◆ teArm_()

void QP::QXThread::teArm_ ( enum_t const sig,
QTimeEvtCtr const nTicks )
privatenoexcept

Arm internal time event private implementation

Description
Internal implementation of arming the private time event for a given timeout at a given system tick rate.
Precondition qxk_xthr:700
  • the time event must be unused
Attention
Must be called from within a critical section

Definition at line 312 of file qxk_xthr.cpp.

◆ teDisarm_()

bool QP::QXThread::teDisarm_ ( )
privatenoexcept

Disarm internal time event private implementation

Description
Internal implementation of disarming the private time event.
Attention
Must be called from within a critical section

Definition at line 357 of file qxk_xthr.cpp.

◆ stackInit_()

void QP::QXThread::stackInit_ ( QP::QXThreadHandler const handler,
void *const stkSto,
std::uint_fast16_t const stkSize )
privatenoexcept

Initialize the private stack of a given eXtended thread (defined in QXK port)

Friends And Related Symbol Documentation

◆ QActive

friend class QActive
friend

Definition at line 93 of file qxk.hpp.

◆ QTimeEvt

friend class QTimeEvt
friend

Definition at line 94 of file qxk.hpp.

◆ QXSemaphore

friend class QXSemaphore
friend

Definition at line 95 of file qxk.hpp.

◆ QXMutex

friend class QXMutex
friend

Definition at line 96 of file qxk.hpp.

Member Data Documentation

◆ m_timeEvt

QTimeEvt QP::QXThread::m_timeEvt
private

Time event to handle blocking timeouts

Definition at line 90 of file qxk.hpp.

◆ QXTHREAD_NO_TIMEOUT

QTimeEvtCtr QP::QXThread::QXTHREAD_NO_TIMEOUT {0U}
staticconstexpr

Definition at line 99 of file qxk.hpp.


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