QActive Class Reference

protected constructor

Performs the first step of active object initialization by assigning the initial pseudostate to the currently active state of the state machine.

Note:

The constructor is protected to prevent direct instantiation of QActive objects. This class is intended only for derivation (abstract class).

Definition at line 261 of file qf.h.

Defer an event to a given separate event queue.

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.

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

See also:

QActive::recall(), QEQueue

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

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 (qf_port.cpp file). Depending on the underlying OS or kernel, the function might block the calling thread when no events are available.

Note:

QActive::get_() is public because it often needs to be called from thread-run routines with difficult to foresee signature (so declaring friendship with such function(s) is not possible.)

See also:

QActive::postFIFO(), QActive::postLIFO()

Posts an event e directly to the event queue of the acitve object me using the First-In-First-Out (FIFO) policy.

Direct event posting is the simplest asynchronous communication method available in QF. The following example illustrates how the Philosopher active obejct posts directly the HUNGRY event to the Table active object.

Note:

The producer of the event (Philosopher in this case) must only "know" the recipient (Table) by a generic (QActive *QDPP_table) pointer, but the specific definition of the Table class is not required.

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 QHsm::dispatch(), or QFsm::dispatch() function.

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

Note:

The LIFO policy should be used only with great caution because it alters order of events in the queue.

See also:

QActive::postFIFO()

Recall a deferred event from a given event queue.

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.

QActive::recall() returns the pointer to the recalled event to the caller. The function returns NULL if no event has been recalled.

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

See also:

QActive::defer(), QEQueue, QActive::postLIFO()

Definition at line 43 of file qa_defer.cpp.

Traditional loop-structured thread routine for an active object.

This function is only used when QF is ported to a traditional RTOS/Kernel. QActive::run() is structured as a typical endless loop, which blocks on the event queue get() operation of an active object. When an event becomes available, it's dispatched to the active object's state machine and after this recycled with QF::gc(). The loop might optionally use the QActive::m_running flag to terminate and cause QActive::run() to return which is often the cleanest way to terminate the thread.

Definition at line 35 of file qa_run.cpp.

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

The function takes six arguments. prio is the priority of the active object. QF allows you to start up to 63 active objects, each one having a unique priority number between 1 and 63 inclusive, where higher numerical values correspond to higher priority (urgency) of the active object relative to the others. qSto[] and qLen arguments are the storage and size of the event queue used by this active object. stkSto and stkSize are the stack storage and size in bytes. Please note that a per-active object stack is used only when the underlying OS requies it. If the stack is not required, or the underlying OS allocates the stack internally, the stkSto should be NULL and/or stkSize should be 0. ie is an optional initialization event that can be used to pass additional startup data to the active object. (Pass NULL if your active object does not expect the initialization event).

Note:

This function is strongly OS-dependent and must be defined in the QF port to a particular platform.

The following example shows starting of the Philosopher object when a per-task stack is required:

Definition at line 85 of file qvanilla.cpp.

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

The preferred way of calling this function is from within the active object that needs to stop (that's why this function is protected). In other words, an active object should stop itself rather than being stopped by some other entity. This policy works best, because only the active object itself "knows" when it has reached the appropriate state for the shutdown.

Note:

This function is strongly OS-dependent and should be defined in the QF port to a particular platform. This function is optional in embedded systems where active objects never need to be stopped.

Definition at line 101 of file qvanilla.cpp.

Subscribes for delivery of signal sig to the active object.

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.

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

See also:

QF::publish(), QActive::unsubscribe(), and QActive::unsubscribeAll()

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

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.

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 rise an assertion.

See also:

QF::publish(), QActive::subscribe(), and QActive::unsubscribeAll()

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

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:

QF::publish(), QActive::subscribe(), and QActive::unsubscribe()

The QK scheduler.

Note:

The QK scheduler must be always called with the interrupts locked and unlocks interrupts internally.

The signature of QK_schedule_() depends on the policy of locking and unlocking interrupts. When the interrupt lock key is not used (QF_INT_KEY_TYPE undefined), the signature is as follows:
void QK_schedule_(void);

However, when the interrupt key lock is used (QF_INT_KEY_TYPE defined), the signature is different:
void QK_schedule_(QF_INT_KEY_TYPE intLockKey);

For the internal use, these differences are hidden by the macro QK_SCHEDULE_.

The QK extended scheduler for interrupt context.

Note:

The QK extended exscheduler must be always called with the interrupts locked and unlocks interrupts internally.

The signature of QK_scheduleExt_() depends on the policy of locking and unlocking interrupts. When the interrupt lock key is not used (QF_INT_KEY_TYPE undefined), the signature is as follows:
void QK_scheduleExt_(void);

However, when the interrupt key lock is used (QF_INT_KEY_TYPE defined), the signature is different:
void QK_scheduleExt_(QF_INT_KEY_TYPE intLockKey);

OS-dependent per-thread object.

This data might be used in various ways, depending on the QF port. In some ports m_osObject is used to block the calling thread when the native QF queue is empty. In other QF ports the OS-dependent object might be used differently.

Definition at line 135 of file qf.h.

QF priority associated with the active object.

See also:

QActive::start()

Definition at line 150 of file qf.h.

The Boolean loop variable determining if the thread routine of the active object is running.

This flag is only used with the traditional loop-structured thread routines. Clearing this flag breaks out of the thread loop, which is often the cleanest way to terminate the thread. The following example illustrates the thread routine for Win32:

Definition at line 160 of file qf.h.

OS-dependent representation of the thread of the active object.

This data might be used in various ways, depending on the QF port. In some ports m_thread is used store the thread handle. In other ports m_thread can be the pointer to the Thread-Local-Storage (TLS).

Definition at line 145 of file qf.h.