QXThread Class Reference

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

#include <qxk.hpp>

Inheritance diagram for QXThread:

Public Member Functions
	QXThread (QXThreadHandler const handler, std::uint_fast8_t const tickRate=0U) noexcept
	public constructor More...
bool	delayCancel () noexcept
	cancel the delay More...
void	init (void const *const e, std::uint_fast8_t const qs_id) override
	Overrides QHsm::init() More...
void	init (std::uint_fast8_t const qs_id) override
	Overrides QHsm::init() More...
void	dispatch (QEvt const *const e, std::uint_fast8_t const qs_id) override
	Overrides QHsm::dispatch() 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
	Posts an event e directly to the event queue of the extended thread using the First-In-First-Out (FIFO) policy. More...
void	postLIFO (QEvt const *const e) noexcept override
	Posts an event directly to the event queue of the extended thread using the Last-In-First-Out (LIFO) policy. More...
Public Member Functions inherited from QActive
virtual 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)
	Starts execution of an active object and registers the object with the framework. More...
virtual 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)
	Overloaded start function (no initialization parameter) More...
void	stop ()
	Stops execution of an active object and removes it from the framework's supervision. More...
virtual bool	post_ (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. More...
virtual 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. More...
QEvt const *	get_ () noexcept
	Get an event from the event queue of an 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
	Unsubscribes from the delivery of signal sig to the active object. More...
void	unsubscribeAll () const noexcept
	Unsubscribes from the delivery of all signals 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 () const noexcept
	Get the priority of the active object. More...
void	setPrio (std::uint_fast8_t const prio) noexcept
	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...
void	register_ () noexcept
	Register this active object to be managed by the framework. More...
void	unregister_ () noexcept
	Un-register the active object from the framework. More...
Public Member Functions inherited from QHsm
virtual void	init (void const *const e, std::uint_fast8_t const qs_id)
	Executes the top-most initial transition in QP::QHsm. More...
virtual void	init (std::uint_fast8_t const qs_id)
	overloaded init(qs_id) More...
virtual void	dispatch (QEvt const *const e, std::uint_fast8_t const qs_id)
	Dispatches an event to QP::QHsm. More...
QStateHandler	state () const noexcept
	Obtain the current state (state handler function) More...
virtual QStateHandler	getStateHandler () noexcept
	Get the current state handler of the QP::QHsm. More...
bool	isIn (QStateHandler const s) noexcept
	Tests if a given state is part of the current active state configuration. 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
	Get a message from the private message queue (block if no messages) More...
Static Public Member Functions inherited from QActive
static void	psInit (QSubscrList *const subscrSto, enum_t const maxSignal) noexcept
	Publish-subscribe initialization. More...
static void	publish_ (QEvt const *const e, void const *const sender, std::uint_fast8_t const qs_id) noexcept
	Publish event to all subscribers of a given signal e->sig More...
static void	thread_ (QActive *act)
	Thread routine for executing an active object act More...
Static Public Member Functions inherited from QHsm
static QState	top (void *const me, QEvt const *const e) noexcept
	The top-state handler. More...

Static Public Attributes
static QXThread	idle
	the idle thread of the QXK kernel More...
Static Public Attributes inherited from QActive
static QActive *	registry_ [QF_MAX_ACTIVE+1U]
	Internal array of registered active objects. More...
static QSubscrList *	subscrList_
	pointer to the array of all subscriber AOs for a given event signal More...
static enum_t	maxPubSignal_
	The maximum published signal (the size of the subscrList_ array) More...
Static Public Attributes inherited from QHsm
static constexpr std::int_fast8_t	MAX_NEST_DEPTH_ {6}
	Maximum nesting depth of states in HSM. More...

Private Member Functions
void	block_ () const noexcept
	Block the extended thread. More...
void	unblock_ () const noexcept
	Unblock the extended thread. More...
void	teArm_ (enum_t const sig, std::uint_fast16_t const nTicks) noexcept
	Arm the private time event. More...
bool	teDisarm_ () noexcept
	Disarm the private time event. More...

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

Friends
class	QXSemaphore
class	QXMutex

Additional Inherited Members
Public Types inherited from QHsm
enum	ReservedHsmSignals : QSignal { Q_ENTRY_SIG = 1U , Q_EXIT_SIG , Q_INIT_SIG }
	Reserved signals by the HSM-style state machine implementation strategy. More...
enum	QStateRet : std::uint_fast8_t {   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 }
	All possible return values from state-handlers. More...
Public Attributes inherited from QActive
std::uint8_t	m_prio
	QF priority (1..QF_MAX_ACTIVE) of this active object. More...
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_init (void const *const tatbl) noexcept
	Helper function to specify an initial 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_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...
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

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 thread-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 (std::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
 
std::uint32_t stack_blinky[80]; // stack for the thread
 
int main() {
    . . .
    // initialize and start Blinky extended thread
    blinky.start(5U, // priority
                 nullptr, 0, // message queue (not used)
                 stack_blinky, sizeof(stack_blinky), // stack
                 nullptr);     // initialization event
    . . .
    return QP::QF::run(); // run the application
}

Definition at line 181 of file qxk.hpp.

Constructor & Destructor Documentation

QXThread()

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

noexcept

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 ticking rate associated with this thread for timeouts in this thread (see QXThread::delay() and TICK_X())

Note

Must be called only ONCE before QXThread::start().

Definition at line 82 of file qxk_xthr.cpp.

Member Function Documentation

delay()

bool delay ( std::uint_fast16_t const  nTicks )

staticnoexcept

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 the delay expired and false if it was cancelled by call to QTimeEvt::delayCancel()

Note

For the delay to work, the TICK_X() macro needs to be called periodically at the associated clock tick rate.

See also

QP::QXThread, QTimeEvt::tick_()

Precondition

this function 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.

also: the thread must NOT be holding a scheduler lock

Definition at line 93 of file qxk_xthr.cpp.

delayCancel()

bool delayCancel ( )

noexcept

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

queueGet()

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

staticnoexcept

The QXThread::queueGet() operation allows the calling extended thread to receive QP events (see QP::QEvt) 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 QP::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 nullptr, the event was delivered. Otherwise the event pointer of nullptr 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 149 of file qxk_xthr.cpp.

init() [1/2]

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

overridevirtual

Reimplemented from QHsm.

Definition at line 237 of file qxk_xthr.cpp.

init() [2/2]

void init ( std::uint_fast8_t const  qs_id )

overridevirtual

Reimplemented from QHsm.

Definition at line 247 of file qxk_xthr.cpp.

dispatch()

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

overridevirtual

Reimplemented from QHsm.

Definition at line 253 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 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() {
     . . .
 
    QP::QF::init();  // initialize the framework and the underlying RT kernel
    BSP::init(); // initialize the BSP
    . . .
    // start the extended threads...
    static QP::QEvt const *test1QueueSto[5];
    static uint64_t test1StackSto[64];
    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]
    . . .
    // start active objects (basic threads)...
    static QP::QEvt const *tableQueueSto[N_PHILO];
    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
}

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 QXThread).

Reimplemented from QActive.

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

Reimplemented from QActive.

Definition at line 313 of file qxk.hpp.

post_()

bool post_ ( QEvt const *const  e, std::uint_fast16_t const  margin, void const *const  sender  )

overridevirtualnoexcept

Extended threads can be configured (in QXThread::start()) to have a private event queue. In that case, QP events (see QP::QEvt) can be asynchronously posted or published to the extended thread. The thread can wait (and block) on its queue and then it can process the delivered event.

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

Precondition

event pointer must be valid

Reimplemented from QActive.

Definition at line 312 of file qxk_xthr.cpp.

postLIFO()

void postLIFO ( QEvt const *const  e )

overridevirtualnoexcept

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

QXThread::post_(), QActive::postLIFO_()

Reimplemented from QActive.

Definition at line 443 of file qxk_xthr.cpp.

block_()

void block_ ( ) const

privatenoexcept

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

unblock_()

void unblock_ ( ) const

privatenoexcept

Internal implementation of unblocking the given extended thread.

Note

must be called from within a critical section

Definition at line 457 of file qxk_xthr.cpp.

teArm_()

void teArm_ ( enum_t const  sig, std::uint_fast16_t const  nTicks  )

privatenoexcept

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

teDisarm_()

bool teDisarm_ ( )

privatenoexcept

Internal implementation of disarming the private time event.

Note

Must be called from within a critical section

Definition at line 510 of file qxk_xthr.cpp.

Friends And Related Function Documentation

QXSemaphore

friend class QXSemaphore

friend

Definition at line 188 of file qxk.hpp.

QXMutex

friend class QXMutex

friend

Definition at line 189 of file qxk.hpp.

Member Data Documentation

m_timeEvt

QTimeEvt m_timeEvt

private

Definition at line 185 of file qxk.hpp.

idle

QXThread idle

static

Definition at line 194 of file qxk.hpp.

---

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

• qxk.hpp
• qxk_xthr.cpp