The OMReactive class is the framework base class for all reactive objects and implements basic event handling functionality. It is declared in the file omreactive.h.
Reactive objects process events, typically via statecharts or activity diagrams. The primary interfaces for reactive objects are the gen and takeTrigger methods.
Triggered operations are synchronous events that affect the reactive class state. The generated code creates an event, then passes it to the reactive class by calling the takeTrigger method. For additional information about triggered operations, see Dispatching triggered operations.
Sender objects apply the gen method to send an event to a receiver, which inherits from OMReactive. The event is then queued inside a thread. See Generating and queuing an event.
The execute method waits on the thread's event queue. When an event is present on the queue, it dispatches it to the appropriate OMReactive object using the takeTrigger method.
This protected attribute specifies whether the reactive object (the concrete object derived from OMReactive) is also an active object. An active object creates its own thread and also inherits from an OMThread object.
The default value is 0 or FALSE.
If the reactive object is an active object, the user application will call the thread start; otherwise, it will not.
OMBoolean active;
This protected attribute specifies whether the reactive object is used by the framework itself (it is not a user-defined object).
The default value is 0 or FALSE, and is specified by OMReactive, the constructor for a reactive object.
The frameworkInstance attribute can be used to model the Rational® Rhapsody® framework in terms of itself. The default value is FALSE; you would not normally want to change the default.
OMBoolean frameworkInstance;
This protected attribute activates an object that has null transitions as part of the default transition.
OMStartBehaviorEvent myStartBehaviorEvent;
This protected attribute defines the internal state (as opposed to the user-class state in the statechart) of the reactive object.
The default value is OMRDefaultStatus and is specified by OMReactive, the constructor for a reactive object.
long omrStatus;
This protected attribute specifies that the consumption of an event is guarded with a mutex (a binary semaphore).
The default value is 0 or FALSE, and is specified by OMReactive, the constructor for a reactive object. toGuardReactive is set to TRUE automatically by code generation, based on user modeling.
OMBoolean toGuardReactive;
Specifies that the event was consumed. It is defined as follows:
#define eventConsumed
OMReactive::OMTakeEventCompleted
Specifies that the event was completed, but was not consumed. It is defined as follows:
#define eventNotConsumed
OMReactive::OMTakeEventCompletedEventNotConsumed
Specifies the default value for the omrStatus attribute. This is used by OMReactive.
const long OMRDefaultStatus = 0x00000000L;
Defines the default thread for an OMReactive object. The default value is 0 or NULL, which tells the OMReactive object to process its events on the system default active class.
#define OMDefaultThread 0
Used to set and get the OMReactive internal state stored in omrStatus. It is used in conjunction with omrStatusto stop event dispatching.
OMRInDtor does not provide protection from mutual exclusion (an attempt to dispatch an event to a class deleted on another thread). If you want to provide mutual exclusion protection, refer to the Rational Rhapsody code generation documentation.
const long OMRInDtor = 0x00020000L;
Used to get and set the OMReactive internal state stored in omrStatus. It is used in conjunction with omrStatus to determine whether null transitions (transitions with no trigger) need to be taken in the generated code.
const long OMRNullConfig = 0x00000001L;
Used to get and set the OMReactive internal state stored in omrStatus. It is used in conjunction with omrStatus to determine whether an OMReactive instance should take null transitions in the state machine.
const long OMRNullConfigMask = 0x0000FFFFL;
OMRShouldCompleteStartBehavior
Used to get and set the OMReactive internal state stored in omrStatus. It is used in conjunction with omrStatus to determine whether the entry to the state machine on the call to startBehavior was completed, and, if not, whether there are additional null transitions to take.
This bit is set by the startBehavior method if the shouldCompleteRun method returns an omrStatus of TRUE.
This bit is reset by the processEvent method on the first event.
const long OMRShouldCompleteStartBehavior =
0x00080000L;
Used to get and set the OMReactive state stored in omrStatus. It is used in conjunction with omrStatus to determine whether a reactive object is deleted by its active object when it reaches a termination connector in its state machine. This permits statically allocated objects to have a termination connector in their state machine.
const long OMRShouldDelete = 0x00040000L;
Used to get and set the OMReactive internal state stored in omrStatus. It is used in conjunction with omrStatus to allow the safe destruction of a reactive instance by its active instance.
const long OMRShouldTerminate = 0x00010000L;
Generates a new event. The GEN macro uses the gen method, then calls the new operator to create a new event.
The macro is defined as follows:
#define GEN (event) gen (new event)
Generates an event from a GUI. The GEN_BY_GUI macro uses the gen method, then calls the new operator to create a new event. OMGui specifies the GUI thread.
The macro is defined as follows:
#define GEN_BY_GUI (event) gen ((OMEvent*)
(new event), OMGui)
Generates a new event from a sender object to a receiver object. It specifies a sender and is typically used to generate events from external elements, such as a GUI. The GEN_BY_X macro uses the gen method, then calls the new operator (with the sender as a parameter) to create a new event.
The macro is defined as follows
#define GEN_BY_X (event, sender) gen (new event,
sender)
Generates an event from an interrupt service request (ISR). The GEN_ISR macro uses the gen method with the genFromISR parameter specified as TRUE to create a new event from an ISR.
It is the user's responsibility to allocate the event; GEN_ISR itself does not allocate the event.
The macros is defined as follows:
#define GEN_ISR (event) gen (event, TRUE)
For VxWorks, GEN_ISR generates an event with urgent priority that is placed at the head of the event queue. If another event from GEN_ISR occurs before the first one has been processed, it will be placed in front of the previous event. The implementation of GEN_ISR for VxWorks was aimed to address a use case where a reactive object has a flow of "plain" events, and from time to time it gets a single, high-priority event that is placed at the front of the queue for immediate consumption.
If a burst of GEN_ISR events are being injected into the system, you can comment out the setting of the priority in the framework to treat events from interrupts with equal priority. In OMBoolean VxOSMessageQueue::put(void* m, OMBoolean fromISR), comment out the line priority = MSG_PRI_URGENT.
This public relation specifies the active or current event (the one that is now being processed) for the OMReactive instance. The relation is assigned only when an event is taken from the event queue.
The default value is NULL, and is specified by OMReactive, the constructor for a reactive object.
The relation is defined as follows:
OMEvent *event;
Used, in collaboration with the generated code, to protect the event consumption from mutual exclusion between events and triggered operations.
If a user reactive class has a guarded triggered operation, this relation will be set to the OMProtected part of the reactive class, and the takeEvent method will lock the guard before calling processEvent.
const OMProtected * m_eventGuard;
This protected relation specifies the active class that queues events and dispatches events (so they are consumed on the active class's thread) for a reactive object.
There is a one-way relationship between a thread and a reactive class. The thread does not know its reactive class—it might have many. However, the reactive class has a relation to its thread, specified by myThread.
The relation is defined as follows:
OMThread *myThread;
This relation defines the root state of the OMReactive statechart (when the system is using a reusable statechart implementation).
The default value is NULL, and is specified by OMReactive, the constructor for a reactive object.
OMComponentState* rootState;