"The big idea is messaging..."
— Alan Kay

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

Note: This section describes events from the perspective of using them in State Machines. The additional requirements are discussed in section Active Objects, which covers the management of mutable, dynamic events in the QP Framework.

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.

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 has associated parameters that carry the character scan code and the status of the Shift, Ctrl, and Alt keys.

Requirements

RQP001

QP Framework shall allow Application to create event instances

Amplification: QP Application shall be able to create as many event instances as needed. Also, QP Application should be able to create both mutable event instances (in RAM) and immutable event instances (possibly in ROM).

RQP002

Each event instance shall contain the event Signal

Amplification: 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 Application to determine how to handle a given event.

RQP002A

The dynamic range of the event signal shall be compile-time configurable

Amplification: QP 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).

RQP002B

QP Framework may reserve some signals for its internal use

Amplification: QP Framework may need some reserved signals to implement features inside hierarchical state machines. The reserved signals shall have the lowest numerical values.

RQP002C

QP Framework shall provide the lowest numerical value of signals allowed in the Application

Amplification: To avoid conflicts around any reserved event signals, QP 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.

RQP003

QP Framework shall allow Application to create event instances with parameters defined in the Application

Amplification: QP Framework needs to provide a mechanism for QP Application to define event parameters useful for the QP Application, and then to create event instances with these parameters.

RQP004

Event instances may contain other data items for internal event management inside QP Framework

Amplification: Event management in QP Framework might require additional information to be stored inside each event instance. Please see Active Objects for requirements related to event management inside QP Framework.

RQP005

QP Framework may be compile-time configurable to allow customized constructor and other custom operations on event instances

Amplification: When such customization is configured, QP Framework shall invoke the custom construction upon instantiation of an event.

RQP006

QP Framework may be compile-time configurable to allow customized destructor of event instances

Amplification: When such customization is configured, QP Framework shall invoke the custom destructor right before recycling the event instance.

OverviewState Machines