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
	Constructor of an extended-thread.
void	init (void const *const e, std::uint_fast8_t const qsId) override
	Virtual function to take the top-most initial transition in the state machine.
void	init (std::uint_fast8_t const qsId) override
	Virtual function to take the top-most initial transition in the state machine (overloaded).
void	dispatch (QEvt const *const e, std::uint_fast8_t const qsId) override
	Virtual function to dispatch an event to the state machine.
void	start (QPrioSpec const prioSpec, QEvtPtr const qSto, std::uint_fast16_t const qLen, void const stkSto, std::uint_fast16_t const stkSize, void const *const par=nullptr)
QTimeEvt const *	getTimeEvt () const &
QTimeEvt const *	getTimeEvt () const &&=delete
bool	delayCancel () noexcept
	Cancel the delay.
Public Member Functions inherited from QP::QActive
bool	isIn (QStateHandler const stateHndl) noexcept override
	Virtual function to check whether the state machine is in a given state.
QStateHandler	getStateHandler () const noexcept override
	Virtual method for getting the current state handler.
QStateHandler	childState (QStateHandler const parentHandler) noexcept
void	setAttr (std::uint32_t attr1, void const *attr2=nullptr)
	Generic setting of additional attributes (defined in some QP ports).
void	start (QPrioSpec const prioSpec, QEvtPtr const qSto, std::uint_fast16_t const qLen, void const stkSto, std::uint_fast16_t const stkSize, void const *const par=nullptr)
	Starts execution of an active object and registers the object with the framework.
void	stop ()
	Stops execution of an active object and removes it from the framework's supervision.
void	register_ () noexcept
	Register this active object to be managed by the framework.
void	unregister_ () noexcept
	Un-register the active object from the framework.
void	post_ (QEvt const const e, 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.
bool	postx_ (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.
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.
QEvt const *	get_ () noexcept
	Get an event from the event queue of an active object.
void	subscribe (QSignal const sig) const noexcept
	Subscribes for delivery of signal sig to the active object.
void	unsubscribe (QSignal const sig) const noexcept
	Unsubscribes from the delivery of signal sig to the active object.
void	unsubscribeAll () const noexcept
	Unsubscribes from the delivery of all signals to the active object.
bool	defer (QEQueue const eq, QEvt const const e) const noexcept
	Defer an event to a given separate event queue.
bool	recall (QEQueue *const eq) noexcept
	Recall a deferred event from a given event queue.
std::uint16_t	flushDeferred (QEQueue *const eq, std::uint_fast16_t const num=0xFFFFU) const noexcept
	Flush the specified deferred queue eq.
std::uint8_t	getPrio () const noexcept
QACTIVE_THREAD_TYPE const &	getThread () const &
QACTIVE_THREAD_TYPE const &	getThread () const &&=delete
void	setThread (QACTIVE_THREAD_TYPE const &thr) noexcept
QACTIVE_OS_OBJ_TYPE const &	getOsObject () const &
QACTIVE_OS_OBJ_TYPE const &	getOsObject () const &&=delete
virtual bool	postFromISR (QEvt const const e, std::uint_fast16_t const margin, void par, void const *const sender) noexcept
	The "FromISR" variant used in the QP port to "FreeRTOS".
Public Member Functions inherited from QP::QAsm
virtual	~QAsm () noexcept
	Virtual destructor of the QP::QAsm abstract base class.
QStateHandler	state () const noexcept
QMState const *	stateObj () const noexcept

Static Public Member Functions
static bool	delay (QTimeEvtCtr const nTicks) noexcept
	Delay (block) the current extended thread for a specified # ticks.
static QEvt const *	queueGet (QTimeEvtCtr const nTicks=QXTHREAD_NO_TIMEOUT) noexcept
	Obtain a message from the private message queue (block if no messages).
Static Public Member Functions inherited from QP::QActive
static std::uint16_t	getQueueUse (std::uint_fast8_t const prio) noexcept
static std::uint16_t	getQueueFree (std::uint_fast8_t const prio) noexcept
static std::uint16_t	getQueueMin (std::uint_fast8_t const prio) noexcept
static void	psInit (QSubscrList *const subscrSto, QSignal const maxSignal) noexcept
	Publish event to all subscribers of a given signal e->sig.
static void	publish_ (QEvt const const e, void const const sender, std::uint_fast8_t const qsId) noexcept
	Publish event to all subscribers of a given signal e->sig.
static void	evtLoop_ (QActive *act)
	Event loop thread routine for executing an active object act (defined some in QP ports).
static QActive *	fromRegistry (std::uint_fast8_t const prio)
static void	publishFromISR (QEvt const e, void par, void const *sender) noexcept
	The "FromISR" variant used in the QP port to "FreeRTOS".
Static Public Member Functions inherited from QP::QAsm
static constexpr QState	Q_HANDLED ()
static constexpr QState	Q_UNHANDLED ()
static constexpr QState	QM_HANDLED ()
static constexpr QState	QM_UNHANDLED ()
static constexpr QState	QM_SUPER ()
static QState	top (void const me, QEvt const const e) noexcept
	Top state handler that ignores all events.

Static Public Attributes
static constexpr QTimeEvtCtr	QXTHREAD_NO_TIMEOUT {0U}
Static Public Attributes inherited from QP::QAsm
static constexpr QState	Q_RET_SUPER {0U}
static constexpr QState	Q_RET_UNHANDLED {1U}
static constexpr QState	Q_RET_HANDLED {2U}
static constexpr QState	Q_RET_TRAN {3U}
static constexpr QState	Q_RET_TRAN_HIST {4U}
static constexpr QState	Q_RET_IGNORED {5U}
static constexpr QState	Q_RET_ENTRY {6U}
static constexpr QState	Q_RET_EXIT {7U}
static constexpr QState	Q_RET_TRAN_INIT {8U}
static constexpr QSignal	Q_EMPTY_SIG {0U}
static constexpr QSignal	Q_ENTRY_SIG {1U}
static constexpr QSignal	Q_EXIT_SIG {2U}
static constexpr QSignal	Q_INIT_SIG {3U}
static constexpr QMState const *	QM_STATE_NULL { nullptr }
static constexpr QActionHandler const	Q_ACTION_NULL { nullptr }

Private Member Functions
void	block_ () const noexcept
	Block QXThread private implementation.
void	unblock_ () const noexcept
	Unblock QXThread private implementation.
void	teArm_ (QSignal const sig, QTimeEvtCtr const nTicks) noexcept
	Arm internal time event private implementation.
bool	teDisarm_ () noexcept
	Disarm internal time event private implementation.
void	stackInit_ (QP::QXThreadHandler const handler, void *const stkSto, std::uint_fast16_t const stkSize) noexcept
	Initialize the private stack of a given eXtended thread (defined in QXK port).

Static Private Member Functions
static void	timeout_ (QActive *const act)
	Process timeout in QXThread (either delay or during blocking).

Private Attributes
QTimeEvt	m_timeEvt
	Time event to handle blocking timeouts.

Friends
class	QActive
class	QTimeEvt
class	QXSemaphore
class	QXMutex
class	QS

Additional Inherited Members
Public Attributes inherited from QP::QAsm
QAsmAttr	m_state
	Current state (pointer to the current state-handler function).
QAsmAttr	m_temp
	Temporary storage for target/act-table etc.
Protected Member Functions inherited from QP::QActive
	QActive (QStateHandler const initial) noexcept
	QActive constructor (abstract base class).
Protected Member Functions inherited from QP::QAsm
	QAsm () noexcept
	Constructor of the QP::QAsm base class.
QState	tran (QStateHandler const target) noexcept
	Internal helper function to take a state transition in sublclasses of QP::QAsm.
QState	tran_hist (QStateHandler const hist) noexcept
	Internal helper function to take a state transition to history in sublclasses of QP::QAsm.
QState	super (QStateHandler const superstate) noexcept
	Internal helper function to indicate superstate of a given state in sublclasses of QP::QAsm.
QState	qm_tran (void const *const tatbl) noexcept
	Internal helper function to take a state transition in QP::QMsm.
QState	qm_tran_init (void const *const tatbl) noexcept
QState	qm_tran_hist (QMState const const hist, void const const tatbl) noexcept
	Internal helper function to take a state transition to history in QP::QMsm.
QState	qm_entry (QMState const *const s) noexcept
	Internal helper function to execute state entry actions in QP::QMsm.
QState	qm_exit (QMState const *const s) noexcept
	Internal helper function to execute state exit actions in QP::QMsm.

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 79 of file qxk.hpp.

Constructor & Destructor Documentation

◆ QXThread()

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

explicitnoexcept

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

Reimplemented from QP::QActive.

Definition at line 63 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 89 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)

Reimplemented from QP::QActive.

Definition at line 71 of file qxk_xthr.cpp.

◆ start()

void QP::QXThread::start	(	QPrioSpec const	prioSpec,
		QEvtPtr *const	qSto,
		std::uint_fast16_t const	qLen,
		void *const	stkSto,
		std::uint_fast16_t const	stkSize,
		void const *const	par = nullptr )

Definition at line 326 of file qxk_xthr.cpp.

◆ getTimeEvt() [1/2]

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

inline

Definition at line 102 of file qxk.hpp.

◆ getTimeEvt() [2/2]

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

delete

◆ 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().

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 79 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 125 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.

Definition at line 142 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.

Attention: Must be called from within a critical section

Definition at line 236 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 249 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 260 of file qxk_xthr.cpp.

◆ teArm_()

void QP::QXThread::teArm_	(	QSignal 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.

Attention: Must be called from within a critical section

Definition at line 272 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 313 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).

◆ QActive

friend class QActive

friend

Definition at line 131 of file qxk.hpp.

◆ QTimeEvt

friend class QTimeEvt

friend

Definition at line 132 of file qxk.hpp.

◆ QXSemaphore

friend class QXSemaphore

friend

Definition at line 133 of file qxk.hpp.

◆ QXMutex

friend class QXMutex

friend

Definition at line 134 of file qxk.hpp.

◆ QS

friend class QS

friend

Definition at line 135 of file qxk.hpp.

Member Data Documentation

◆ QXTHREAD_NO_TIMEOUT

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

staticconstexpr

Definition at line 81 of file qxk.hpp.

◆ m_timeEvt

QTimeEvt QP::QXThread::m_timeEvt

private

Time event to handle blocking timeouts.

Definition at line 116 of file qxk.hpp.

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


QP/C++ 8.1.2 Real-Time Event Framework

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

◆ start()

◆ getTimeEvt() [1/2]

◆ getTimeEvt() [2/2]

◆ delay()

◆ delayCancel()

◆ queueGet()

◆ block_()

◆ unblock_()

◆ timeout_()

◆ teArm_()

◆ teDisarm_()

◆ stackInit_()

Friends And Related Symbol Documentation

◆ QActive

◆ QTimeEvt

◆ QXSemaphore

◆ QXMutex

◆ QS

Member Data Documentation

◆ QXTHREAD_NO_TIMEOUT

◆ m_timeEvt