OMEvent is
the base class for all events defined in Rational® Rhapsody® and
from which the code generator implicitly derives all events. OMEvent is
an abstract class and is declared in the file event.h.
OMEvent has two important data attributes:
- destination - Every event "knows" which OMReactive started
it. When the thread wants to send the event to its destination, it
looks to the destination attribute to find the target OMReactive instance.
- lid - Every event has an ID. Rational Rhapsody code
generation automatically generates sequential IDs, but you can also
specify the ID associated with an event. You might want to do this,
for example, to maintain the ID across compilation, add more events,
do special things with an event, or use a specific ID because you
are sending it out of the application.
You
can specify the event ID in the Rational Rhapsody properties at two
levels: an individual
event ID or a base ID number for every package. Using the base number, Rational Rhapsody assigns every event a sequential
ID number.
Every object and event that inherits
from OMEvent can add additional data to store event-specific
information. For example, if you want to send an event with the current
time, you can add an attribute with the relevant type name and the
event will have access to the additional data.
Event
parameters are mapped by code generation to data members of event
classes that inherit from OMEvent.
OMEvent is
also the base class for two special kinds of events:
- timeout event - In addition to the lId attribute
for an event, a timeout has a Timeout attribute.
The code generator automatically generates different timeouts. The Timeout attribute
specifies how long to wait until the timeout is expired and activated.
The Timeout attribute specifies the absolute time
when the timeout will be executed (m_Time + Timeout).
- delay event - The delay event is used infrequently.
Its purpose is to delay a thread. When the thread gets a delay event,
it pauses for the delay time.
Events are
normally generated in two steps,
which are encapsulated within the GEN macro in the
framework:
- An event class is instantiated,
resulting in a
pointer to the event.
- The event is queued by
adding the new event pointer
to the receiver's event queue.
Once the
event has been instantiated and added
to the event queue of the receiver, the event is ready to be "sent."
The success of the send operation relies on the assumption that the
memory address space of the sender and receiver are the same. However,
this is not always the case.
For example, the
following are some examples of scenarios in which the sender and receiver
memory address spaces are most likely different:
- The event is sent between different processes in
the same host.
- The event is sent between distributed
applications.
- The sender and receiver are mapped
to different
memory partitions.
One
common way
to solve this problem is to marshall the information. Marshalling
means to convert the event into raw data, send it using frameworks
such as publish/subscribe, and then convert the raw data back to its
original form at the receiving end. High-level solutions, such as
CORBA™, automatically generate the necessary code, but with low-level
solutions, you should take explicit care. Rational Rhapsody allows
you to specify how to marshall, and not marshall, events and instances
by creating "standard operations" to handle this task.
For low-level solutions, you may use one of these partial
animation methods:
- In the same selected
component, using properties
to enable/disable the animation of specific packages, classes, and
so on.
- Mix animated and non-animated components
in the
same executable.
To support partial animation,
C++ code generation
has the following characteristics:
- Inheritance
of user classes and events from AOM elements
was canceled.
- For each animated user class
(event), a friend
class is created in the code. The friend class is responsible for
the animation of the user class.
- All the animation-specific
methods are now part
of the animation friend class.
To support partial animation, OXF has the following
characteristics:
- Inheritance from AOM classes
was
canceled (OMEvent and OMReactive).
- Attributes that were protected by #ifdef
_OMINSTRUMENT are now regular attributes, with default values
that can be handled by the non-animated version of the framework.
- Animation friend classes were added for the framework-visible
events.
deleteAfterConsume -
determines whether an event
is deleted after it is consumed
destination -
specifies an OMReactive instance
frameworkEvent -
specifies whether an event is a framework event
lid -
specifies a value for an event ID
Constant
summaryOMEventAnyEventId is
a reserved event ID that specifies any event.
OMCancelEventId is
a reserved event ID that specifies a canceled event (an event that
should not be sent to its destination).
OMEventNullId is
a reserved event ID used to consume null transitions.
OMEventStartBehaviorId is
a reserved event ID used for OMStartBehavior events.
OMEventOXFEndEventId is
a reserved event ID used to cleanly close the framework when a COM
server that uses the framework DLL is deleted.
OMEventTimeoutId is
a reserved event ID used for timeouts.
Construction summary- OMEvent
- Constructs an OMEvent object
- ~OMEvent
- Destroys the OMEvent object
Method
summary- Delete
- Deletes
an event instance (releases the memory
used by an event)
- getDestination
- Returns the reactive destination of the event
- getlId
- Returns the event ID
- isCancelledTimeout
- Determines whether the event is canceled
- isDeleteAfterConsume
- Returns TRUE if the event should
be deleted by the event dispatcher (OMThread) after
its consumption
- isFrameworkEvent
- Returns TRUE if the event is an
internal framework event
- isRealEvent
- Returns TRUE if the event is a
null-transition event, timeout, or user event
- isTimeout
- Returns TRUE if the event is a
timeout
- isTypeOf
- Returns TRUE if the event is from
a given type (has the specified ID)
- setDeleteAfterConsume
- Determines whether the
event is deleted
by the event dispatcher (OMThread) after it is consumed
- setDestination
- Sets the event reactive destination
- setFrameworkEvent
- Sets the event to be
considered as a internal framework
event
- setlId
- Sets
the event ID