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

#include "qxk.h"

Inheritance diagram for QXThread:

Public Member Functions
void	QXThread_ctor (QXThread *const me, QXThreadHandler const handler, uint_fast8_t const tickRate)

bool	QXThread_delay (QTimeEvtCtr const nTicks)

bool	QXThread_delayCancel (QXThread *const me)

Public Member Functions inherited from QActive
void	QActive_setAttr (QActive const me, uint32_t attr1, void const attr2)

Static Public Member Functions
QEvt const *	QXThread_queueGet (QTimeEvtCtr const nTicks)

Static Public Member Functions inherited from QActive
void	QActive_psInit (QSubscrList *const subscrSto, enum_t const maxSignal)
	Publish event to all subscribers of a given signal `e->sig`

Public Attributes
QActive	super

Public Attributes inherited from QActive
QAsm	super

Private Member Functions
void	QXThread_block_ (QXThread const *const me)

void	QXThread_unblock_ (QXThread const *const me)

void	QXThread_timeout_ (QActive *const act)

void	QXThread_teArm_ (QXThread *const me, enum_t const sig, QTimeEvtCtr const nTicks)

bool	QXThread_teDisarm_ (QXThread *const me)

void	QXThread_stackInit_ (QActive const me, QXThreadHandler const handler, void const stkSto, uint_fast16_t const stkSize)

Private Attributes
QTimeEvt	timeEvt

QXThread const *	QXThread_dummy

Additional Inherited Members
Protected Member Functions inherited from QActive
void	QActive_ctor (QActive *const me, QStateHandler const initial)
	QActive constructor (abstract base class)

void	QActive_stop (QActive *const me)
	Stops execution of an active object and removes it from the framework's supervision.

void	QActive_subscribe (QActive const *const me, enum_t const sig)
	Subscribes for delivery of signal `sig` to the active object.

void	QActive_unsubscribe (QActive const *const me, enum_t const sig)
	Unsubscribes from the delivery of signal `sig` to the active object.

void	QActive_unsubscribeAll (QActive const *const me)
	Unsubscribes from the delivery of all signals to the active object.

bool	QActive_defer (QActive const const me, struct QEQueue const eq, QEvt const *const e)
	Defer an event to a given separate event queue.

bool	QActive_recall (QActive const me, struct QEQueue const eq)
	Recall a deferred event from a given event queue.

uint_fast16_t	QActive_flushDeferred (QActive const const me, struct QEQueue const eq, uint_fast16_t const num)
	Flush the specified number of events from the deferred queue `eq`

Protected Member Functions inherited from QAsm
void	QAsm_ctor (QAsm *const me)
	Constructor of the QAsm base class.

QState	QHsm_top (QHsm const const me, QEvt const const e)

Protected Attributes inherited from QActive
uint8_t	prio
	QF-priority [1..QF_MAX_ACTIVE] of this AO.

uint8_t	pthre
	Preemption-threshold [1..QF_MAX_ACTIVE] of this AO.

QACTIVE_THREAD_TYPE	thread
	Port-dependent representation of the thread of the active object.

QACTIVE_OS_OBJ_TYPE	osObject
	Port-dependent per-thread object.

QACTIVE_EQUEUE_TYPE	eQueue
	Port-dependent event-queue type (often QEQueue)

uint8_t	prio_dis

uint8_t	pthre_dis

Protected Attributes inherited from QAsm
struct QAsmVtable const *	vptr
	Virtual pointer inherited by all QAsm subclasses (see also Object Orientation)

union QAsmAttr	state
	Current state (pointer to the current state-handler function)

union QAsmAttr	temp
	Temporary storage for target/act-table etc.

Detailed Description

eXtended (blocking) thread of the QXK preemptive kernel

Details

QXThread represents the eXtended (blocking) thread of the QXK kernel. Each extended thread in the application must be represented by the corresponding QXThread instance

Note: Typically, QXThread is instantiated directly in the application code. The customization of the thread occurs in the QXThread_ctor(), 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 "qpc.h"
 
QXThread blinky;  // QXK extended-thread object
 
void main_blinky(QXThread * const me) { // thread function
    while (1) {
        BSP_ledOn();
        QXThread_delay(100U); // BLOCK
        BSP_ledOff();
        QXThread_delay(200U); // BLOCK
    }
}
 
int main() {
    . . .
    // initialize and start blinky thread
    QXThread_ctor(&blinky, &main_blinky, 0);
 
    static uint64_t stack_blinky[40]; // stack for the thread
    QXTHREAD_START(&blinky,
        5U,           // priority
        (void *)0, 0, // event queue (not used)
        stack_blinky, sizeof(stack_blinky), // stack
        (void *)0);   // extra parameter (not used)
    . . .
    return QF_run(); // run the application
}

Definition at line 145 of file qxk.h.

Member Function Documentation

◆ QXThread_ctor()

void QXThread_ctor	(	QXThread *const	me,
		QXThreadHandler const	handler,
		uint_fast8_t const	tickRate )

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,out]	me	current instance pointer (see oop)
[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 "qpc.h"
 
Q_DEFINE_THIS_FILE
 
QXThread blinky;  // QXK extended-thread object
 
void main_blinky(QXThread * const me) { // thread function
    while (1) {
        . . .
    }
}
 
int main() {
    . . .
    // instantiate and start blinky thread
    QXThread_ctor(&blinky, &main_blinky, 0); // <===
 
    static uint64_t stack_blinky[40]; // stack for the thread
    QXTHREAD_START(&blinky,
        5U,           // priority
        (void *)0, 0, // event queue (not used)
        stack_blinky, sizeof(stack_blinky), // stack
        (void *)0);   // extra parameter (not used)
    . . .
    return QF_run(); // run the application
}

◆ QXThread_delay()

bool QXThread_delay ( QTimeEvtCtr const nTicks )

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 91 of file qxk_xthr.c.

◆ QXThread_delayCancel()

bool QXThread_delayCancel ( QXThread *const me )

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 139 of file qxk_xthr.c.

◆ QXThread_queueGet()

QEvt const * QXThread_queueGet ( QTimeEvtCtr const nTicks )

static

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 160 of file qxk_xthr.c.

◆ QXThread_block_()

void QXThread_block_ ( QXThread const *const me )

private

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 258 of file qxk_xthr.c.

◆ QXThread_unblock_()

void QXThread_unblock_ ( QXThread const *const me )

private

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 274 of file qxk_xthr.c.

◆ QXThread_timeout_()

void QXThread_timeout_ ( QActive *const act )

private

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 291 of file qxk_xthr.c.

◆ QXThread_teArm_()

void QXThread_teArm_	(	QXThread *const	me,
		enum_t const	sig,
		QTimeEvtCtr const	nTicks )

private

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 304 of file qxk_xthr.c.

◆ QXThread_teDisarm_()

bool QXThread_teDisarm_ ( QXThread *const me )

private

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 348 of file qxk_xthr.c.

◆ QXThread_stackInit_()

void QXThread_stackInit_	(	QActive *const	me,
		QXThreadHandler const	handler,
		void *const	stkSto,
		uint_fast16_t const	stkSize )

private

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

Member Data Documentation

◆ super

QActive QXThread::super

Definition at line 147 of file qxk.h.

◆ timeEvt

QTimeEvt timeEvt

private

property Time event to handle blocking timeouts

Definition at line 152 of file qxk.h.

◆ QXThread_dummy

QXThread const* QXThread_dummy

private

dummy static member to force QM to generate 'struct QXThread'

property Dummy static member to force QM to generate "struct QXThread"

Definition at line 157 of file qxk.h.

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

Public Member Functions

Static Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ QXThread_ctor()

◆ QXThread_delay()

◆ QXThread_delayCancel()

◆ QXThread_queueGet()

◆ QXThread_block_()

◆ QXThread_unblock_()

◆ QXThread_timeout_()

◆ QXThread_teArm_()

◆ QXThread_teDisarm_()

◆ QXThread_stackInit_()

Member Data Documentation

◆ super

◆ timeEvt

◆ QXThread_dummy