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

#include "qxk.hpp"

Inheritance diagram for QP::QXThread:

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 QActive *	registry_ [QF_MAX_ACTIVE+1U]

static QSubscrList *	subscrList_

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

Details

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

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

Details

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]	handler	the thread-handler function
[in]	tickRate	the 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 76 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.

Details

Synchronously executes the top-most initial transition in a state machine (must be overridden in the subclasses).

Parameters

[in]	e	pointer to an initialization parameter (might be nullptr)
[in]	qsId	QS-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 86 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).

Details

Synchronously executes the top-most initial transition in a state machine. This overloaded version takes no initialization parameter.

Parameters

[in] qsId QS-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.

Details

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]	e	pointer to the event to be dispatched to the MSM
[in]	qsId	QS-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 96 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

Details

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

Parameters

[in] nTicks number 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 106 of file qxk_xthr.cpp.

◆ delayCancel()

bool QP::QXThread::delayCancel ( )

noexcept

Cancel the delay

Details

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 152 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)

Details

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] nTicks number 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 172 of file qxk_xthr.cpp.

◆ block_()

void QP::QXThread::block_ ( ) const

privatenoexcept

Block QXThread private implementation

Details

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

◆ unblock_()

void QP::QXThread::unblock_ ( ) const

privatenoexcept

Unblock QXThread private implementation

Details

Internal implementation of un-blocking the given extended thread.

Attention: Must be called from within a critical section

Definition at line 283 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] act generic QActive* pointer of the thread that times out.

Definition at line 299 of file qxk_xthr.cpp.

◆ teArm_()

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

privatenoexcept

Arm internal time event private implementation

Details

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

◆ teDisarm_()

bool QP::QXThread::teDisarm_ ( )

privatenoexcept

Disarm internal time event private implementation

Details

Internal implementation of disarming the private time event.

Attention: Must be called from within a critical section

Definition at line 356 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:

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QXThread()

Member Function Documentation

◆ init() [1/2]

◆ init() [2/2]

◆ dispatch()

◆ getTimeEvt()

◆ delay()

◆ delayCancel()

◆ queueGet()

◆ block_()

◆ unblock_()

◆ timeout_()

◆ teArm_()

◆ teDisarm_()

◆ stackInit_()

Friends And Related Symbol Documentation

◆ QActive

◆ QTimeEvt

◆ QXSemaphore

◆ QXMutex

Member Data Documentation

◆ m_timeEvt

◆ QXTHREAD_NO_TIMEOUT