OMReactive class

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.

Attribute summary
active - specifies whether the reactive object (the concrete object derived from OMReactive) is also an active object
frameworkInstance - specifies whether the reactive object is used by the framework itself (it is not a user-defined object)
myStartBehaviorEvent - activates an object that has null transitions as part of the default transition
omrStatus - defines the internal state (as opposed to the user-class state in the statechart) of the reactive object
toGuardReactive - specifies that the consumption of an event is guarded with a mutex (a binary semaphore)
Constant summary
eventConsumed - specifies that the event has been consumed.
eventNotConsumed - specifies that the event was completed, but was not consumed.
OMRDefaultStatus - specifies the default value for the omrStatus attribute
OMDefaultThread - defines the default thread for an OMReactive object
OMRInDtor - stops event dispatching
OMRNullConfig - determines whether null transitions (transitions with no trigger) need to be taken in the generated code
OMRNullConfigMask - determines whether an OMReactive instance should take null transitions in the state machine
OMRShouldCompleteStartBeh avior - determines 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
OMRShouldDelete - determines whether a reactive object is deleted by its active object when it reaches a termination connector in its state machine
OMRShouldTerminate - allows the safe destruction of a reactive instance by its active instance
Macro summary
GEN - generates a new event
GEN_BY_GUI - generates an event from a GUI
GEN_BY_X - generates a new event from a sender object to a receiver object
GEN_ISR - generates an event from an interrupt service request (ISR)
Relation summary
event - specifies the active or current event (the one that is now being processed) for the OMReactive instance
m_eventGuard - used, in collaboration with the generated code, to protect the event consumption from mutual exclusion between events and triggered operations
myThread - specifies the active class that queues events and dispatches events (so they are consumed on the thread of the active class) for a reactive object
rootState - defines the root state of the OMReactive statechart (when the system is using a reusable statechart implementation)
Construction summary
OMReactive
Constructs an OMReactive object
~OMReactive
Destroys the OMReactive object
Method summary
cancelEvents
Cancels all the queued events for the reactive object.
processEvent
Is the main event consumption method.
discarnateTimeout
Destroys a timeout object for the reactive object.
doBusy
Sets the value of to 1 or TRUE.
gen
Is used by a sender object to send an event to a receiver object.
_gen
Queues events sent to the reactive object.
getCurrentEvent
Gets the currently processed event.
getThread
Retrieves the thread associated with a reactive object.
handleEventNotConsumed
Is called when an event is not consumed by the reactive class.
handleTONotConsumed
Is called when a triggered operation is not consumed by the reactive class.
incarnateTimeout
Creates a timeout object to be invoked on the reactive object.
inNullConfig
Determines whether an OMReactive instance should take null transitions (transitions without triggers) in the state machine.
isActive
Determines whether a reactive object is also an active object.
isBusy
Returns the current value of the attribute.
isCurrentEvent
Determines whether the specified ID is the currently processed event.
isFrameworkInstance
Determines the current value of the attribute.
isInDtor
Determines whether event dispatching is stopped.
isValid
Makes sure the reactive class is not deleted.
popNullConfig
Decrements the attribute after a null transition is taken.
pushNullConfig
Counts null transitions and increments the omrStatus attribute after a state is exited.
registerWithOMReactive
Registers a user instance as a reactive class in the animation framework
rootState_dispatchEvent
Consumes an event inside a real statechart.
rootState_entDef
Initializes the statechart by taking the default transitions.
rootState_serializeStates
Is a virtual method that performs the actual event consumption.
runToCompletion
Takes all the null transitions (if any) that can be taken after an event has been consumed.
serializeStates
Is called during animation to send state information.
setCompleteStartBehavior
Sets the value of the attribute.
setEventGuard
Is used to set the event guard flag.
setFrameworkInstance
Changes the value of the attribute.
setInDtor
Specifies that event dispatching is stopped.
setMaxNullSteps
Sets the maximum number of null transitions (those without a trigger) that can be taken sequentially in the statechart.
setShouldDelete
Specifies whether a reactive object is deleted by its active object when it reaches a termination connector in its state machine.
setShouldTerminate
Specifies that a reactive instance can be safely destroyed by its active instance.
setThread
Sets the thread of a reactive object.
setToGuardReactive
Specifies the value of the attribute.
shouldCompleteRun
Checks the value of to determine whether there are null transitions to take.
shouldCompleteStartBehavior
Checks the start behavior state.
shouldDelete
Determines whether a reactive object is deleted by its active object when it reaches a termination connector in its state machine.
shouldTerminate
Determines whether a reactive instance can be safely destroyed by its active instance.
startBehavior
Initializes the behavioral mechanism and takes the initial (default) transitions in the statechart before any events are processed.
takeEvent
Is used by the event loop (within the thread) to make the reactive object process an event.
takeTrigger
Consumes a triggered operation event (synchronous event).
terminate
Sets the OMReactive instance to the terminate state (the statechart is entering a termination connector).
undoBusy
Sets the value of the sm_busy attribute to 0 or FALSE.
Attributes and defines

active

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.

It is defined as follows:

OMBoolean active;

frameworkInstance

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.

It is defined as follows:

OMBoolean frameworkInstance;

myStartBehaviorEvent

This protected attribute activates an object that has null transitions as part of the default transition.

It is defined as follows:

OMStartBehaviorEvent myStartBehaviorEvent;

omrStatus

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.

It is defined as follows:

long omrStatus;

toGuardReactive

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.

It is defined as follows:

OMBoolean toGuardReactive;
Constants

eventConsumed

Specifies that the event was consumed. It is defined as follows:

#define eventConsumed 
    OMReactive::OMTakeEventCompleted

eventNotConsumed

Specifies that the event was completed, but was not consumed. It is defined as follows:

#define eventNotConsumed 
    OMReactive::OMTakeEventCompletedEventNotConsumed

OMRDefaultStatus

Specifies the default value for the omrStatus attribute. This is used by OMReactive.

It is defined as follows:

const long OMRDefaultStatus = 0x00000000L;

OMDefaultThread

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.

It is defined as follows:

#define OMDefaultThread 0

OMRInDtor

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.

It is defined as follows:

const long OMRInDtor = 0x00020000L;

OMRNullConfig

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.

It is defined as follows:

const long OMRNullConfig = 0x00000001L;

OMRNullConfigMask

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.

It is defined as follows:

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.

It is defined as follows:

const long OMRShouldCompleteStartBehavior =
    0x00080000L;

OMRShouldDelete

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.

It is defined as follows:

const long OMRShouldDelete = 0x00040000L;

OMRShouldTerminate

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.

It is defined as follows:

const long OMRShouldTerminate = 0x00010000L;
Macros

GEN

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)

GEN_BY_GUI

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)

OMGui is defined in aoxf.h.

GEN_BY_X

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)

GEN_ISR

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.

Relations

event

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;

m_eventGuard

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.

It is defined as follows:

const OMProtected * m_eventGuard;

myThread

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;

rootState

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.

It is defined as follows:

OMComponentState* rootState;

The OMComponentState class is defined in state.h.


Feedback