QP/C++  5.9.5
QP::QActive Class Reference

QActive active object (based on QP::QHsm implementation) More...

#include <qf.h>

Inheritance diagram for QP::QActive:
QP::QHsm QP::QMActive QP::QTicker QP::QXKIdleThread QP::QXThread

Public Member Functions

virtual void start (uint_fast8_t const prio, QEvt const *qSto[], uint_fast16_t const qLen, void *const stkSto, uint_fast16_t const stkSize, QEvt const *const ie)
 Starts execution of an active object and registers the object with the framework. More...
 
virtual void start (uint_fast8_t const prio, QEvt const *qSto[], uint_fast16_t const qLen, void *const stkSto, uint_fast16_t const stkSize)
 Overloaded start function (no initialization event)
 
virtual bool post_ (QEvt const *const e, uint_fast16_t const margin, void const *const sender)
 
virtual void postLIFO (QEvt const *const e)
 Posts an event directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy. More...
 
void unsubscribeAll (void) const
 Un-subscribes from the delivery of all signals to the active object. More...
 
void stop (void)
 Stops execution of an active object and removes it from the framework's supervision. More...
 
void subscribe (enum_t const sig) const
 Subscribes for delivery of signal sig to the active object. More...
 
void unsubscribe (enum_t const sig) const
 Un-subscribes from the delivery of signal sig to the active object. More...
 
bool defer (QEQueue *const eq, QEvt const *const e) const
 Defer an event to a given separate event queue. More...
 
bool recall (QEQueue *const eq)
 Recall a deferred event from a given event queue. More...
 
uint_fast16_t flushDeferred (QEQueue *const eq) const
 Flush the specified deferred queue 'eq'. More...
 
uint_fast8_t getPrio (void) const
 Get the priority of the active object.
 
void setPrio (uint_fast8_t const prio)
 Set the priority of the active object.
 
QEvt const * get_ (void)
 Get an event from the event queue of an active object. More...
 
- Public Member Functions inherited from QP::QHsm
virtual ~QHsm ()
 virtual destructor More...
 
virtual void init (QEvt const *const e)
 Executes the top-most initial transition in QP::QHsm. More...
 
virtual void init (void)
 
virtual void dispatch (QEvt const *const e)
 Dispatches an event to QHsm. More...
 
bool isIn (QStateHandler const s)
 Tests if a given state is part of the current active state configuration. More...
 
QStateHandler state (void) const
 Obtain the current state (state handler function) More...
 
QStateHandler childState (QStateHandler const parent)
 Obtain the current active child state of a given parent. More...
 
QState tran_ (QStateHandler const target)
 internal helper function to record a state transition
 
QState tran_hist_ (QStateHandler const hist)
 internal helper function to record a transition to history
 
QState super_ (QStateHandler const superstate)
 internal helper function to record the superstate
 
QState qm_tran_ (QMTranActTable const *const tatbl)
 internal helper function to record a regular state transition
 
QState qm_tran_hist_ (QMState const *const hist, QMTranActTable const *const tatbl)
 Internal helper function to record a regular state transition.
 
QState qm_tran_init_ (QMTranActTable const *const tatbl)
 Internal helper function to record an initial state transition.
 
QState qm_tran_ep_ (QMTranActTable const *const tatbl)
 Internal helper function to record an transition to an entry point to a submachine state.
 
QState qm_tran_xp_ (QActionHandler const xp, QMTranActTable const *const tatbl)
 Internal helper function to record an transition to an exit point from a submachine state.
 
QState qm_entry_ (QMState const *const s)
 Internal helper function to record a state entry.
 
QState qm_exit_ (QMState const *const s)
 Internal helper function to record a state exit.
 
QState qm_super_sub_ (QMState const *const s)
 Internal helper function to call in a QM action-handler when it passes the event to the host submachine state to handle an event.
 

Public Attributes

uint_fast8_t m_prio
 QF priority associated with the active object.
 

Protected Member Functions

 QActive (QStateHandler const initial)
 protected constructor (abstract class)
 
- Protected Member Functions inherited from QP::QHsm
 QHsm (QStateHandler const initial)
 Protected constructor of QHsm. More...
 

Friends

class QF
 
class QTimeEvt
 
class QTicker
 

Additional Inherited Members

- Public Types inherited from QP::QHsm
enum  ReservedHsmSignals { Q_ENTRY_SIG = 1, Q_EXIT_SIG, Q_INIT_SIG }
 
- Static Public Member Functions inherited from QP::QHsm
static QState top (void *const me, QEvt const *const e)
 the top-state. More...
 
static QState Q_HANDLED (void)
 internal helper function to specify the return of a state-handler when it handles the event.
 
static QState Q_UNHANDLED (void)
 internal helper function to specify the return of a state-handler function when it attempts to handle the event but a guard condition evaluates to false and there is no other explicit way of handling the event.
 
static QState QM_HANDLED (void)
 Internal helper function to call in a QM action-handler when it handles an event.
 
static QState QM_UNHANDLED (void)
 Macro to call in a QM action-handler when it does not handle an event due to a guard condition evaluating to false.
 
static QState QM_SUPER (void)
 Internal helper function to call in a QM action-handler when it passes the event to the superstate for processing.
 

Detailed Description

QActive active object (based on QP::QHsm implementation)

Description
Active objects in QP are encapsulated tasks (each embedding a state machine and an event queue) that communicate with one another asynchronously by sending and receiving events. Within an active object, events are processed in a run-to-completion (RTC) fashion, while QF encapsulates all the details of thread-safe event exchange and queuing.

QP::QActive represents an active object that uses the QP::QHsm-style implementation strategy for state machines. This strategy is tailored to manual coding, but it is also supported by the QM modeling tool. The resulting code is slower than in the QP::QMsm-style implementation strategy.
Note
QP::QActive is not intended to be instantiated directly, but rather serves as the base class for derivation of active objects in the applications.
See also
QP::QMActive
Usage
The following example illustrates how to derive an active object from QP::QActive.
class Philo : public QActive { // derives from QActive
private:
uint8_t m_num; // number of this philosopher
QTimeEvt m_timeEvt; // to timeout thining or eating
public:
Philo::Philo()
: QActive(Q_STATE_CAST(&Philo::initial)),
m_timeEvt(TIMEOUT_SIG, this, 0U)
{}
protected:
static QState initial (Philo * const me, QEvt const *e);
static QState thinking(Philo * const me, QEvt const *e);
static QState hungry (Philo * const me, QEvt const *e);
static QState eating (Philo * const me, QEvt const *e);
};

Definition at line 141 of file qf.h.

Member Function Documentation

◆ defer()

bool QP::QActive::defer ( QEQueue *const  eq,
QEvt const *const  e 
) const

Defer an event to a given separate event queue.

Description
This function is part of the event deferral support. An active object uses this function to defer an event e to the QF-supported native event queue eq. QF correctly accounts for another outstanding reference to the event and will not recycle the event at the end of the RTC step. Later, the active object might recall one event at a time from the event queue.
Parameters
[in]eqpointer to a "raw" thread-safe queue to recall an event from.
[in]epointer to the event to be deferred
Returns
'true' (success) when the event could be deferred and 'false' (failure) if event deferral failed due to overflowing the queue.

An active object can use multiple event queues to defer events of different kinds.

See also
QP::QActive::recall(), QP::QEQueue, QP::QActive::flushDeferred()

Definition at line 70 of file qf_defer.cpp.

◆ flushDeferred()

uint_fast16_t QP::QActive::flushDeferred ( QEQueue *const  eq) const

Flush the specified deferred queue 'eq'.

Description
This function is part of the event deferral support. An active object can use this function to flush a given QF event queue. The function makes sure that the events are not leaked.
Parameters
[in]eqpointer to a "raw" thread-safe queue to flush.
Returns
the number of events actually flushed from the queue.
See also
QP::QActive::defer(), QP::QActive::recall(), QP::QEQueue

Definition at line 133 of file qf_defer.cpp.

◆ get_()

QEvt const * QP::QActive::get_ ( void  )

Get an event from the event queue of an active object.

Description
The behavior of this function depends on the kernel used in the QF port. For built-in kernels (Vanilla or QK) the function can be called only when the queue is not empty, so it doesn't block. For a blocking kernel/OS the function can block and wait for delivery of an event.
Returns
a pointer to the received event. The returned pointer is always valid (can't be NULL).

Definition at line 253 of file qf_actq.cpp.

◆ post_()

bool QP::QActive::post_ ( QEvt const *const  e,
uint_fast16_t const  margin,
void const *const  sender 
)
virtual
Description
Direct event posting is the simplest asynchronous communication method available in QF.
Parameters
[in,out]epointer to the event to be posted
[in]marginnumber 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.
Returns
The function returns true (success) if the posting succeeded (with the provided margin) and false (failure) when the posting fails.
Attention
This function should be called only via the macro POST() or POST_X().
Note
The QP::QF_NO_MARGIN value of the margin argument 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.
Direct event posting should not be confused with direct event dispatching. In contrast to asynchronous event posting through event queues, direct event dispatching is synchronous. Direct event dispatching occurs when you call QP::QMsm::dispatch().
This function is used internally by a QF port to extract events from the event queue of an active object. This function depends on the event queue implementation and is sometimes implemented in the QF port (file qf_port.cpp). Depending on the underlying OS or kernel, the function might block the calling thread when no events are available.
Usage
extern QActive *AO_Table;
QP::QState Philo::hungry(Philo * const me, QP::QEvt const * const e) {
QP::QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
TableEvt *pe = Q_NEW(TableEvt, HUNGRY_SIG);
pe->philoNum = PHILO_ID(me);
AO_Table->POST(pe, me);
status = Q_HANDLED();
break;
}
. . .
default: {
status = Q_SUPER(&QHsm::top);
break;
}
}
return status;
}
See also
QActive::postLIFO()
Precondition
event pointer must be valid
Note
assert if event cannot be posted and dropping events is not acceptable

Reimplemented in QP::QTicker, and QP::QXThread.

Definition at line 98 of file qf_actq.cpp.

◆ postLIFO()

void QP::QActive::postLIFO ( QEvt const *const  e)
virtual

Posts an event directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy.

Description
posts an event to the event queue of the active object using the Last-In-First-Out (LIFO) policy.
Note
The LIFO policy should be used only for self-posting and with caution because it alters order of events in the queue.
Parameters
[in]epointer to the event to post to the queue
See also
QActive::post_()

Reimplemented in QP::QTicker, and QP::QXThread.

Definition at line 195 of file qf_actq.cpp.

◆ recall()

bool QP::QActive::recall ( QEQueue *const  eq)

Recall a deferred event from a given event queue.

Description
This function is part of the event deferral support. An active object uses this function to recall a deferred event from a given QF event queue. Recalling an event means that it is removed from the deferred event queue eq and posted (LIFO) to the event queue of the active object.
Parameters
[in]eqpointer to a "raw" thread-safe queue to recall an event from.
Returns
'true' if an event has been recalled and 'false' if not.
Note
An active object can use multiple event queues to defer events of different kinds.
See also
QP::QActive::recall(), QP::QEQueue, QP::QActive::postLIFO_()

Definition at line 92 of file qf_defer.cpp.

◆ start()

void QP::QActive::start ( uint_fast8_t const  prio,
QEvt const *  qSto[],
uint_fast16_t const  qLen,
void *const  stkSto,
uint_fast16_t const  stkSize,
QEvt const *const  ie 
)
virtual

Starts execution of an active object and registers the object with the framework.

Description
Starts execution of the AO and registers the AO with the framework.
Parameters
[in]priopriority at which to start the active object
[in]qStopointer to the storage for the ring buffer of the event queue (used only with the built-in QP::QEQueue)
[in]qLenlength of the event queue (in events)
[in]stkStopointer to the stack storage (must be NULL in QV)
[in]stkSizestack size [bytes]
[in]iepointer to the optional initial event (might be NULL).
Note
This function should be called via the macro START().
Usage
The following example shows starting an AO when a per-task stack is needed
static Philo l_philo[N]; // N Philosopher active objects
static QEvt const *l_philQueueSto[N][N]; // storage for Philo event queues
static int l_philoStk[N][256]; // stacks for the Philosopher active objects
main() {
. . .
for (n = 0; n < N; ++n) {
TableEvt ie; // initialization event for the Philosopher HSM
ie.philNum = n;
l_philo[n].start((uint8_t)(n*10 + 1), // priority
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]), // queue
l_philoStk[n], sizeof(l_philoStk[n]), // uC/OS-II stack
&ie); // initialization event
}
. . .
}
Precondition
AO cannot be started from an ISR, the priority must be in range and the stack storage must not be provided, because the QK kernel does not need per-AO stacks.
the priority must be in range and the stack storage must not be provided, because the QV kernel does not need per-AO stacks.
AO cannot be started from an ISR, the priority must be in range and the stack storage must not be provided, because the QK kernel does not need per-AO stacks.

Reimplemented in QP::QXThread.

Definition at line 172 of file qk.cpp.

◆ stop()

void QP::QActive::stop ( void  )

Stops execution of an active object and removes it from the framework's supervision.

Description
The preferred way of calling this function is from within the active object that needs to stop. In other words, an active object should stop itself rather than being stopped by someone else. This policy works best, because only the active object itself "knows" when it has reached the appropriate state for the shutdown.
Note
By the time the AO calls QP::QActive::stop(), it should have unsubscribed from all events and no more events should be directly-posted to it.
Precondition
QActive::stop() must be called from the AO that wants to stop.
QActive_stop() must be called from the AO that wants to stop.

Definition at line 215 of file qk.cpp.

◆ subscribe()

void QP::QActive::subscribe ( enum_t const  sig) const

Subscribes for delivery of signal sig to the active object.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Subscribing to an event means that the framework will start posting all published events with a given signal sig to the event queue of the active object.
Parameters
[in]sigevent signal to subscribe

The following example shows how the Table active object subscribes to three signals in the initial transition:

See also
QP::QF::publish_(), QP::QActive::unsubscribe(), and QP::QActive::unsubscribeAll()

Definition at line 197 of file qf_ps.cpp.

◆ unsubscribe()

void QP::QActive::unsubscribe ( enum_t const  sig) const

Un-subscribes from the delivery of signal sig to the active object.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from an event means that the framework will stop posting published events with a given signal sig to the event queue of the active object.
Parameters
[in]sigevent signal to unsubscribe
Note
Due to the latency of event queues, an active object should NOT assume that a given signal sig will never be dispatched to the state machine of the active object after un-subscribing from that signal. The event might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events.
Un-subscribing from a signal that has never been subscribed in the first place is considered an error and QF will raise an assertion.
See also
QP::QF::publish_(), QP::QActive::subscribe(), and QP::QActive::unsubscribeAll()

Definition at line 239 of file qf_ps.cpp.

◆ unsubscribeAll()

void QP::QActive::unsubscribeAll ( void  ) const

Un-subscribes from the delivery of all signals to the active object.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from all events means that the framework will stop posting any published events to the event queue of the active object.
Note
Due to the latency of event queues, an active object should NOT assume that no events will ever be dispatched to the state machine of the active object after un-subscribing from all events. The events might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events. Also, the alternative event-delivery mechanisms, such as direct event posting or time events, can be still delivered to the event queue of the active object.
See also
QP::QF::publish_(), QP::QActive::subscribe(), and QP::QActive::unsubscribe()

Definition at line 281 of file qf_ps.cpp.


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