Structure Viewpoint elaborates the base classes and interfaces identified in the architecture Context Viewpoint with their design details and structural static relationships. The Structure Design Viewpoint also provides examples of using the QP/C++ Framework classes in QP/C++ Applications and is used to address the following concerns:
packages and classes
interfaces
functionality and responsibilities
data structures
control flow
concurrency and parallelism
resource management
The model kind used to illustrate the Structure Viewpoint is the UML class diagram shown in Figure SDS-CLS (static view). It depicts base classes comprising QP/C++ Framework and their specializations in the QP/C++ Application shown at the bottom of Figure SDS-CLS.
Figure SDS-CLS: Core classes in QP/C++ Framework and their relation to QP/C++ Application.
Sub-Layer View
The Sub-Layer View view in the Structure Viewpoint focuses on the internal layering of the QP/C++ Framework, which has the following objectives:
promote modularity.
separation of concerns into passive and active elements.
QEP Event Processor is intentionally separated out to allow QP/C++ Applications to directly use just the passive state machines (without Active Objects). QP/C++ Applications that use just the QEP Event Processor can still benefit from the QM modeling tool↑ , which can generate code that requires only passive state machines.
describing the responsibilities of each class to achieve high cohesion within a class and loose coupling among classes.
defining the inheritance hierarchies and polymorphic behavior to promote reuse and flexibility.
ensuring data encapsulation within classes to maintain safety, integrity, and security.
SDS_QP_QEvt
SDS_QP_QEvt : QEvt event class.
Description
The QP QEvt class (see Figure SDS-CLS [11]) represents both immutable and mutable events in QP/C++ Framework. It can be instantiated directly (concrete class), in which case it represents events without parameters. QP/C++ Applications can also inherit and extend QP QEvt to add custom event parameters.
Attention
Event parameters must be included in the event instance directly. Therefore, the QP QEvt sublcasses are restricted to have both "standard layout" and be "trivially copyable". In QP/C++ this means that QP QEvt sublcasses should:
NO pointers or references; The only exception is passing opaque pointer(s) to Active Objects intended as recipients of future events.
contain NO virtual functions (consequence of no virtual pointer);
contain NO access specifiers (protected, and private);
contain NO non-trivial copy or move constructor;
contain NO non-trivial copy or move assignment operator;
contain NO destructor.
Event Attributes
The QP QEvt class has the following data attributes:
event signal of type QSignal with compile-time configurable dynamic range
event reference counter with dynamic range 0 .. (2 * QF_MAX_ACTIVE). For mutable events, the reference counter stores the number of outstanding references to that event instance. For immutable events, the reference counter is fixed at 1.
event tag with two fileds:
bits 4-7 store the event pool ID of the event (for dynamic events) and fixed at 0 for immutable events.
bits 0-3 implement the Safety Function described below:
Safety Function
The QP QEvt class implements the Duplicate Inverse Storage technique for data integrity self-monitoring of the volatile QP QEvt::refCtr_ reference counter attribute. For memory efficiency, only 4 least-significant bits 0:3 of the reference counter are monitoried in bits 0:3 of the QP QEvt::evtTag_ attribute.
Backward Traceability
SRS_QP_EVT_00 : QP/C++ Framework shall provide Event abstraction to QP/C++ Application
SRS_QP_EVT_20 : Each event instance shall contain the event Signal
SRS_QP_EVT_30 : QP/C++ Framework shall allow Application to create event instances with Parameters defined by the Application
SRS_QP_EVT_31 : Event abstraction may contain other data items for internal event management inside QP/C++ Framework
QP::QEvt::evtTag_ : Event "tag" contains pool-ID plus the Duplicate Inverted Storage of the QEvt::refCtr_
SDS_QP_QAsm
SDS_QP_QAsm : QAsm Abstract state machine class.
Description
The QP QAsm class (see Figure SDS-CLS [12]) is the abstract base class (ABC) for all state machines in QP/C++ Framework. The QP QAsm class specifies the abstract state machine interface.
State Machine Interface
The state machine interface defined in the QP QAsm class consists of:
init() operation executes the top-most initial transition. It must be executed only once.
dispatch() operation dispatches a given even to the state machine for RTC processing. It must be executed for every event.
isIn() (is in-state) operation returns 'true' if the state machine is-in the given state. Note that being "in-a-state" means also being in all the superstates of that state.
State Machine Attributes
current state (state variable): stores the current state of the state machhine.
temporary attribute: stores transition target during a state transition. Also used to implement the Safety Function described below.
Safety Function
In the stable state configuration (between the RTC steps) the subclasses of QP QAsm use the temporary attribute for the Duplicate Inverse Storage of the QP QAsm::state attribute.
Backward Traceability
SRS_QP_SM_00 : QP/C++ Framework shall provide support for hierarchical state machines both for Active Objects and for passive event-driven objects in the Application
SRS_QP_SM_10 : QP/C++ Framework shall support multiple and interchangeable State Machine Implementation Strategies
SRS_QP_SM_25 : All State Machine Implementation Strategies provided by QP/C++ Framework might supply a method for checking if a state machine is in a given state
Forward Traceability
QP::QAsm : Abstract State Machine class (state machine interface)
Safety Function
The QP QHsm class implements the Fixed Loop Bound technique for all not explicitly terminated loops. This prevents malformed state machines specifications (from the QP/C++ Application layer) to "hang" or crash the event processor.
Backward Traceability
SRS_QP_SM_20 : QP/C++ Framework shall provide a State Machine Implementation Strategy optimized for "manual coding"
SRS_QP_SM_22 : All State Machine Implementation Strategies provided by QP/C++ Framework shall be bidirectionally traceable
SRS_QP_SM_23 : QP/C++ Framework shall ensure that the current event does not change and is accessible to the state machine implementation over the entire RTC step.
SRS_QP_SM_24 : All State Machine Implementation Strategies provided by QP/C++ shall allow Applications to easily access the instance variables associated with a given state machine object
SRS_QP_SM_30 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support hierarchical state machines with features specified in the sub-requirements SRS_QP_SM_3x
SRS_QP_SM_31 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support states capable of holding hierarchically nested substates
SRS_QP_SM_32 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support entry actions to states
SRS_QP_SM_33 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support exit actions from states
SRS_QP_SM_34 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support nested initial transitions in composite states
SRS_QP_SM_35 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support transitions between states at any level of nesting
SRS_QP_SM_36 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support internal transitions in states
SRS_QP_SM_37 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support guard conditions to be attached to regular and internal transitions
SRS_QP_SM_38 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support top-most initial transition that shall be explicitly triggered independently from instantiation of the state machine object
SRS_QP_SM_39 : All State Machine Implementation Strategies provided by QP/C++ Framework should support transitions to history. Both shallow and deep histories shall be supported
SRS_QP_SM_40 : State Machine Implementation Strategies provided by QP/C++ Framework might supply the top-state
Forward Traceability
QP::QHsm : Hierarchical State Machine class (QHsm-style state machine implementation strategy)
Safety Function
The QP QMsm class implements the Fixed Loop Bound technique for all not explicitly terminated loops. This prevents malformed state machines specifications (from the QP/C++ Application layer) to "hang" or crash the event processor.
Backward Traceability
SRS_QP_SM_21 : QP/C++ Framework should provide a State Machine Implementation Strategy optimized for "automatic code generation"
SRS_QP_SM_22 : All State Machine Implementation Strategies provided by QP/C++ Framework shall be bidirectionally traceable
SRS_QP_SM_23 : QP/C++ Framework shall ensure that the current event does not change and is accessible to the state machine implementation over the entire RTC step.
SRS_QP_SM_24 : All State Machine Implementation Strategies provided by QP/C++ shall allow Applications to easily access the instance variables associated with a given state machine object
SRS_QP_SM_30 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support hierarchical state machines with features specified in the sub-requirements SRS_QP_SM_3x
SRS_QP_SM_31 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support states capable of holding hierarchically nested substates
SRS_QP_SM_32 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support entry actions to states
SRS_QP_SM_33 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support exit actions from states
SRS_QP_SM_34 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support nested initial transitions in composite states
SRS_QP_SM_35 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support transitions between states at any level of nesting
SRS_QP_SM_36 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support internal transitions in states
SRS_QP_SM_37 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support guard conditions to be attached to regular and internal transitions
SRS_QP_SM_38 : All State Machine Implementation Strategies provided by QP/C++ Framework shall support top-most initial transition that shall be explicitly triggered independently from instantiation of the state machine object
SRS_QP_SM_39 : All State Machine Implementation Strategies provided by QP/C++ Framework should support transitions to history. Both shallow and deep histories shall be supported
SRS_QP_SM_40 : State Machine Implementation Strategies provided by QP/C++ Framework might supply the top-state
Forward Traceability
QP::QMsm : Hierarchical State Machine class (QMsm-style state machine implementation strategy)
SDS_QP_QActive
SDS_QP_QActive : QActive Active Object class.
Description
The QP QActive class (Figure SDS-CLS [23]) is a base class for derivation of concrete Active Objects in the QP/C++ Application. QP QActive inherits QP QAsm, which means that an Active Object in QP/C++ can be treated as a state machine with the standard interface. QP QActive implements this interface by delegating to the QP QHsm state machine implementation.
Active Object Priority QP QActive owns the unique priority attribute, which must be in range 1..QF_MAX_ACTIVE, inclusive.
Event Queue QP QActive owns the event-queue attribute, whose type depends on the underlying real-time kernel. Therefore, the event-queue type is compile-time configurable. When QP/C++ is used with one of the built-in kernels (QV, QK, QXK), the QActive event queue is configured to be QP QEQueue. However, when QP/C++ Framework runs on a 3rd-party RTOS, typically the RTOS' message queue is adapted as an event queue.
Remarks
The event queue for Active Objects requires multiple-write, but only single-read capability. Also, blocking the queue is only required when event-queue is empty but not when it is full. Finally, the Active Object queue in QP/C++ Framework passes only pointers to events. Standard RTOS message queues are significantly more complex than required by Active Objects because they typically allow multiple-write as well as multiple-read access and often support variable-length data (not only pointer-sized data). Usually message queues also allow blocking when the queue is empty and when the queue is full, and both types of blocking can be timed out. Naturally, all this extra functionality, which you don't really need in QP/C++ Framework, comes at an extra cost in CPU and memory usage.
Thread of Execution QP QActive owns the execution thread attribute, whose type depends on the underlying real-time kernel. Therefore, the thread type is compile-time configurable. When QP/C++ is used with one of the built-in kernels (QV, QK, QXK), the QActive thread attribute isn't really needed and is used to hold MPU settings. However, when QP/C++ Framework runs on a 3rd-party RTOS, the QActive thread attribute holds the RTOS thread.
OS Object
The "operating system object" attribute is
Backward Traceability
SRS_QP_AO_00 : QP/C++ Framework shall provide the Active Object abstraction to QP/C++ Application
SRS_QP_AO_70 : Active Object abstraction shall provide support for state machines.
Forward Traceability
SDS_QP_QMctive
SDS_QP_QMctive : QMctive Active Object class.
Description
The QP QMActive class (Figure SDS-CLS [24]) derives from QP QActive base class, so it inherits all its properties. The only difference is that, QP QMActive implements the state machine interface by delegating to the QP QMsm state machine implementation.
Backward Traceability
SRS_QP_AO_00 : QP/C++ Framework shall provide the Active Object abstraction to QP/C++ Application
SRS_QP_AO_70 : Active Object abstraction shall provide support for state machines.
Forward Traceability
SDS_QP_QTimeEvt
SDS_QP_QTimeEvt : QTimeEvt time event class.
Description
The QP QActive class (Figure SDS-CLS [23]) is a base class for derivation of concrete Active Objects in the QP/C++ Application. QP QActive encapsulates the unique priority, event-queue, execution context, and state machine for the Active Object. QP QActive inherits QP QAsm, which means that an Active Object in QP/C++ can be treated as a state machine with the standard interface. QP QActive implements this interface by delegating to the QP QHsm state machine implementation.
Backward Traceability
SRS_QP_TM_00 : QP/C++ Framework shall support Time Events.
