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

#include <qxthread.hpp>

Inheritance diagram for QXThread:

Collaboration diagram for QXThread:

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

void	postLIFO (QEvt const *const e) noexcept override
	Posts an event directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy. More...

Public Member Functions inherited from QActive
void	stop (void)
	Stops execution of an active object and removes it from the framework's supervision. More...

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
	Tests if a given state is part of the current active state configuration. More...

QStateHandler	state (void) const noexcept
	Obtain the current state (state handler function) 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
	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
	Helper function to specify a regular 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_init (void const *const tatbl) noexcept
	Helper function to specify an initial state transition 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...

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

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

}

uint32_t
unsigned long int uint32_t
exact-width 32-bit unsigned int
Definition: 16bit/stdint.h:31

QP::QF::run
static int_t run(void)
Transfers control to QF to run the application.
Definition: qk.cpp:137

QP::QXThread
Extended (blocking) thread of the QXK preemptive kernel.
Definition: qxthread.hpp:66

QP::QXThread::delay
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] 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

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]	prio	priority at which to start the extended thread
[in]	qSto	pointer 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]	qLen	length of the event queue [in events], or zero if queue not used
[in]	stkSto	pointer to the stack storage (must be provided)
[in]	stkSize	stack size [in bytes] (must not be zero)
[in]	par	pointer 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

}

uint64_t
unsigned long long uint64_t
exact-width 64-bit unsigned int
Definition: 16bit/stdint.h:32

QP::QF::init
static void init(void)
QF initialization.
Definition: qk.cpp:78

Q_DIM
#define Q_DIM(array_)
Helper macro to calculate static dimension of a 1-dim array_.
Definition: qassert.h:337

qpcpp.hpp
QP/C++ public interface including backwards-compatibility layer.

QP::QEvt
QEvt base class.
Definition: qep.hpp:209

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 QP::QXThread::QXThread()).

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]	e	pointer to the event to be posted
[in]	margin	number 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]	sender	pointer 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] e pointer 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:

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QXThread()

Member Function Documentation

◆ delay()

◆ delayCancel()

◆ queueGet()

◆ init() [1/2]

◆ init() [2/2]

◆ dispatch()

◆ start() [1/2]

◆ start() [2/2]

◆ post_()

◆ postLIFO()

◆ block_()

◆ unblock_()

◆ teArm_()

◆ teDisarm_()

Friends And Related Function Documentation

◆ QXSemaphore

◆ QXMutex

Field Documentation

◆ m_timeEvt