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)
	Constructor of an extended-thread.
void	QXThread_start (QXThread const me, QPrioSpec const prioSpec, QEvtPtr const qSto, uint_fast16_t const qLen, void const stkSto, uint_fast16_t const stkSize, void const const par)
bool	QXThread_delay (QTimeEvtCtr const nTicks)
	Delay (block) the current extended thread for a specified # ticks.
bool	QXThread_delayCancel (QXThread *const me)
	Cancel the delay.
Public Member Functions inherited from QActive
void	QActive_setAttr (QActive const me, uint32_t attr1, void const attr2)
	Generic setting of additional attributes (defined in some QP ports).
void	QActive_start (QActive const me, QPrioSpec const prioSpec, QEvtPtr const qSto, uint_fast16_t const qLen, void const stkSto, uint_fast16_t const stkSize, void const const par)
	Starts execution of an active object and registers the object with the framework.

Static Public Member Functions
QEvt const *	QXThread_queueGet (QTimeEvtCtr const nTicks)
	Obtain a message from the private message queue (block if no messages).
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.
uint16_t	QActive_getQueueUse (uint_fast8_t const prio)
uint16_t	QActive_getQueueFree (uint_fast8_t const prio)
uint16_t	QActive_getQueueMin (uint_fast8_t const prio)
	This function returns the minimum of free entries of the given event queue.

Protected Attributes
QActive	super
Protected Attributes inherited from QActive
QAsm	super
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).
Protected Attributes inherited from QAsm
struct QAsmVtable const *	vptr
	Virtual pointer inherited by all QAsm subclasses (see also SAS_QP_OO).
union QAsmAttr	state
	Current state (pointer to the current state-handler function).
union QAsmAttr	temp
	Temporary storage for target/act-table etc..

Private Member Functions
void	QXThread_block_ (QXThread const *const me)
	Block QXThread private implementation.
void	QXThread_unblock_ (QXThread const *const me)
	Unblock QXThread private implementation.
void	QXThread_timeout_ (QActive *const act)
	Process timeout in QXThread (either delay or during blocking).
void	QXThread_teArm_ (QXThread *const me, enum_t const sig, QTimeEvtCtr const nTicks)
	Arm internal time event private implementation.
bool	QXThread_teDisarm_ (QXThread *const me)
	Disarm internal time event private implementation.
void	QXThread_stackInit_ (QXThread const me, QXThreadHandler const handler, void const stkSto, uint_fast16_t const stkSize)
	Initialize the private stack of a given eXtended thread (defined in QXK port).

Private Attributes
QTimeEvt	timeEvt
	Time event to handle blocking timeouts.

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

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 88 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 SAS_QP_OO)
[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
}

Definition at line 48 of file qxk_xthr.c.

◆ QXThread_start()

void QXThread_start	(	QXThread *const	me,
		QPrioSpec const	prioSpec,
		QEvtPtr *const	qSto,
		uint_fast16_t const	qLen,
		void *const	stkSto,
		uint_fast16_t const	stkSize,
		void const *const	par )

Definition at line 319 of file qxk_xthr.c.

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

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

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

Attention: Must be called from within a critical section

Definition at line 224 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 237 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 249 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.

Attention: Must be called from within a critical section

Definition at line 262 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 305 of file qxk_xthr.c.

◆ QXThread_stackInit_()

void QXThread_stackInit_	(	QXThread *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 super

protected

Definition at line 89 of file qxk.h.

◆ timeEvt

QTimeEvt timeEvt

private

Time event to handle blocking timeouts.

Definition at line 90 of file qxk.h.

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


QP/C 8.1.1 Real-Time Event Framework

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ QXThread_ctor()

◆ QXThread_start()

◆ QXThread_delay()

◆ QXThread_delayCancel()

◆ QXThread_queueGet()

◆ QXThread_block_()

◆ QXThread_unblock_()

◆ QXThread_timeout_()

◆ QXThread_teArm_()

◆ QXThread_teDisarm_()

◆ QXThread_stackInit_()

Member Data Documentation

◆ super

◆ timeEvt