Events

Active ObjectsState Machines

Concepts & Definitions

An Event is the specification of some occurrence that may potentially have significance to the system under consideration. Upon such an occurrence, a corresponding Event (class) is instantiated, and the generated Event Instance (object) outlives the instantaneous occurrence that generated it.

Event Instances (a.k.a. Messages) are objects specifically designed for communication and synchronization within an event-driven system, such as a QP/C Application. Once generated, an Event Instance (a.k.a. Message) is propagated to the system, where it can trigger various Actions. These Actions might involve generating secondary Event Instances.

Remarks

This section describes events from the perspective of using them in State Machines and Active Objects. Additional concepts and requirements related to event management in QP/C Framework are discussed in sections Event Delivery Mechanisms and Event Memory Management.

Event Signal

An Event always has information about the type of occurrence that generated the Event Instance ("what happened"), which will be called Signal in this document. Event Signals are typically enumerated constants that indicate which specific occurrence out of a set of all possible (enumerated) occurrences has generated the Event Instance.

Figure SRS-EVT-SIG: Relationship between Event-Signals and Events. A Signal must unambiguously identify an Event type.

Event Parameters

An Event can have (optionally) associated Parameters, allowing the Event Instance to convey the quantitative information regarding that occurrence. For example, a Keystroke event generated by pressing a key on a computer keyboard might have associated parameters that carry the character scan code and the status of the Shift, Ctrl, and Alt keys.

Requirements

SRS_QP_EVT_00

SRS_QP_EVT_00 : QP/C Framework shall provide Event abstraction to QP/C Application
Description The QP/C Framework shall define a common Event abstraction, so that it can be instantiated, exchanged, and correctly interpreted by both the QP/C Application and QP/C Framework.
Forward Traceability SAS_QP_CLS : QP/C Framework base classes SDS_QA_QHsm_decl : Declaring QHsm subclass. SDS_QA_QHsm_top_init : Implementing the top-most initial pseudo-state. SDS_QA_QHsm_state : Implementing a state and its nesting. SDS_QA_QHsm_entry : Implementing state entry action. SDS_QA_QHsm_exit : Implementing state exit action. SDS_QA_QHsm_nest_init : Implementing nested initial transition. SDS_QA_QHsm_tran : Implementing state transition. SDS_QA_QHsm_intern : Implementing internal transition. SDS_QA_QHsm_choice : Implementing choice point and guard conditions. SDS_QA_QHsm_hist : Implementing state history. SDS_QA_QHsm_hist_tran : Implementing transition to history. SDS_QA_QMsm_decl : Declaring QMsm subclass. SDS_QA_QMsm_top_init : Implementing the top-most initial pseudo-state. SDS_QA_QMsm_state : Implementing a state and its nesting. SDS_QA_QMsm_entry : Implementing state entry action. SDS_QA_QMsm_exit : Implementing state exit action. SDS_QA_QMsm_nest_init : Implementing nested initial transition. SDS_QA_QMsm_tran : Implementing state transition. SDS_QA_QMsm_intern : Implementing internal transition. SDS_QA_QMsm_choice : Implementing choice point and guard conditions. SDS_QA_QMsm_hist : Implementing state history. SDS_QA_QMsm_hist_tran : Implementing transition to history. SDS_QP_QEvt : QEvt event class. QEvt : Event class QEvt::sig : Signal of the event (see Event Signal) QEvt::refCtr_ : Event reference counter. QEvt::evtTag_ : Event "tag" contains pool-ID plus the Duplicate Inverted Storage of the QEvt::refCtr_ QEvt::QEvt_init() : Event without parameters initialization

SRS_QP_EVT_20

SRS_QP_EVT_20 : Each event instance shall contain the event Signal
Description The event Signal carries the information about the occurrence that generated the given event instance. The Signal needs to be easily accessible to the QP/C Application to determine how to handle a given event.
Forward Traceability QEvt::sig : Signal of the event (see Event Signal) SDS_QP_QEvt : QEvt event class. QEvt : Event class QEvt::sig : Signal of the event (see Event Signal) QEvt::refCtr_ : Event reference counter. QEvt::evtTag_ : Event "tag" contains pool-ID plus the Duplicate Inverted Storage of the QEvt::refCtr_ QEvt::QEvt_init() : Event without parameters initialization

SRS_QP_EVT_21

SRS_QP_EVT_21 : The dynamic range of the event signal shall be compile-time configurable
Description QP/C Framework should be compile-time configurable to allow choosing the optimal dynamic range for the event signals while minimizing the size of the event instances. The following dynamic range of event signals should be configurable: 255 signals (1 byte of memory per Signal), 64K signals (2 bytes of memory per Signal), and 4G signals (4 bytes of memory per Signal).
Forward Traceability

SRS_QP_EVT_22

SRS_QP_EVT_22 : QP/C Framework may reserve some signals for its internal use
Description QP/C Framework may need some reserved signals to implement features inside hierarchical state machines. The reserved signals shall have the lowest numerical values.
Forward Traceability

SRS_QP_EVT_23

SRS_QP_EVT_23 : QP/C Framework shall provide the lowest numerical value of signals allowed in the Application
Description To avoid conflicts around any reserved event signals, QP/C Framework shall provide the lowest numerical limit for Application-level signals. In other words, the reserved signals will have numerical values 0 .. (SIGNAL_OFFSET - 1), and the Application-level signals will have values SIGNAL_OFFSET .. SIGNAL_DYNAMIC_RANGE.
Forward Traceability

SRS_QP_EVT_30

SRS_QP_EVT_30 : QP/C Framework shall allow Application to create event instances with Parameters defined by the Application
Description The Event abstraction shall provide a mechanism for QP/C Application to define event parameters useful for the QP/C Application, and then to create event instances with these parameters.
Forward Traceability QEvt::refCtr_ : Event reference counter. QEvt::evtTag_ : Event "tag" contains pool-ID plus the Duplicate Inverted Storage of the QEvt::refCtr_ Q_EVT_CAST : Perform downcast of an event onto a subclass of QEvt class_ SDS_QP_QEvt : QEvt event class. QEvt : Event class QEvt::sig : Signal of the event (see Event Signal) QEvt::refCtr_ : Event reference counter. QEvt::evtTag_ : Event "tag" contains pool-ID plus the Duplicate Inverted Storage of the QEvt::refCtr_ QEvt::QEvt_init() : Event without parameters initialization

SRS_QP_EVT_31

SRS_QP_EVT_31 : Event abstraction may contain other data items for internal event management inside QP/C Framework
Description Event management in QP/C Framework might require additional information to be stored inside each event instance. Please see Event Memory Management for requirements related to event management inside QP/C Framework.
Forward Traceability QEvt::refCtr_ : Event reference counter. QEvt::evtTag_ : Event "tag" contains pool-ID plus the Duplicate Inverted Storage of the QEvt::refCtr_ SDS_QP_QEvt : QEvt event class. QEvt : Event class QEvt::sig : Signal of the event (see Event Signal) QEvt::refCtr_ : Event reference counter. QEvt::evtTag_ : Event "tag" contains pool-ID plus the Duplicate Inverted Storage of the QEvt::refCtr_ QEvt::QEvt_init() : Event without parameters initialization

SRS_QP_EVT_40

SRS_QP_EVT_40 : QP/C Framework may be compile-time configurable to allow customized constructor and other custom operations on event instances
Description When such customization is configured, QP/C Framework shall invoke the custom construction upon instantiation of an event.
Forward Traceability QEvt::QEvt_init() : Event without parameters initialization

SRS_QP_EVT_41

SRS_QP_EVT_41 : QP/C Framework may be compile-time configurable to allow customized destructor of event instances
Description When such customization is configured, QP/C Framework shall invoke the custom destructor right before recycling the event instance.
Forward Traceability

Active ObjectsState Machines