ptolemy.domains.de.kernel
Class DEEvent

java.lang.Object
  ptolemy.domains.de.kernel.DEEvent

All Implemented Interfaces:

java.lang.Comparable

public class DEEvent
extends java.lang.Object
implements java.lang.Comparable

This class defines the structure of events in the DE domain. Conceptually, a DE event is a trigger that contains a tag and a reference to its destination actor. The purpose of a DE event is to schedule its destination actor to fire at the timestamp and microstep specified by its tag.

A tag is a tuple of a timestamp and a microstep. The timestamp is the model time when the event exists. The microstep defines the order of a sequence of (simultaneous) events that exist at the same model time.

A DE event is associated with a destination, which is either an actor or an IO port of an actor. A DE event, whose destination is an actor, is called a pure event. A pure event does not have a destination IO port. A DE event, whose destination is an IO port, is called a trigger event. A trigger event has a destination actor, which is the container of the destination IO port.

A DE event also has a depth, which is the topology information of its destinations. For a pure event, the depth is that of its destination actor. For a trigger event, the depth is that of its destination IO port. A larger value of depth indicates a lower priority when the simulator processes events with the same tag.

Two DE events can be compared to see which one happens first. The order is defined by the relationship between their time stamps, microsteps, and depths. See DEEventQueue for more details. DE events can be compared by using the compareTo() method.

This class is final to improve the simulation performance because new events get created and discarded through the whole simulation.

Since:

Ptolemy II 0.2

Version:

$Id: DEEvent.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Lukito Muliadi, Edward A. Lee, Haiyang Zheng, Contributor: Christopher Brooks

Accepted Rating:

Green (hyzheng)

Proposed Rating:

Green (hyzheng)

Field Summary

protected Actor	_actor The destination actor.
protected int	_depth The depth of this event.
protected IOPort	_ioPort The destination IO port.
protected int	_microstep The microstep of this event.
protected int	_priority The priority of the event (used when the timestamp, depth and microstep cannot resolve a conflict.
protected Time	_timestamp The timestamp of the event.

Constructor Summary

private	DEEvent(Actor actor, IOPort ioPort, Time timeStamp, int microstep, int depth) Construct a pure event with the specified destination actor, IO port timestamp, microstep, and depth.
	DEEvent(Actor actor, Time timeStamp, int microstep, int depth) Construct a pure event with the specified destination actor, timestamp, microstep, and depth.
	DEEvent(IOPort ioPort, Time timeStamp, int microstep, int depth) Construct a trigger event with the specified destination IO port, timestamp, microstep, and depth.

Method Summary

(package private) void	_updateDepth(int newDepth) Update the depth of this event if the new depth is no less than 0.
Actor	actor() Return the destination actor for this event.
int	compareTo(DEEvent event) Compare the tag and depth of this event with those of the argument event for the order.
int	compareTo(java.lang.Object event) Compare this event with the argument event for an order.
int	depth() Return the depth of this event.
boolean	equals(java.lang.Object object) Indicate whether some other object is equal to this DE Event.
int	hashCode() Return the hash code for the event object.
boolean	hasTheSameTagAndDepthAs(DEEvent event) Return true if this event has the same tag with the specified one, and their depths are the same.
boolean	hasTheSameTagAs(DEEvent event) Return true if this event has the same tag as the argument DE event.
IOPort	ioPort() Return the destination IO port of this event.
int	microstep() Return the microstep of this event.
Time	timeStamp() Return the timestamp.
java.lang.String	toString() Return a description of the event, including the the tag, depth, and destination information.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

_actor

protected Actor _actor

The destination actor.

_depth

protected int _depth

The depth of this event.

_ioPort

protected IOPort _ioPort

The destination IO port.

_microstep

protected int _microstep

The microstep of this event.

_priority

protected int _priority

The priority of the event (used when the timestamp, depth and microstep cannot resolve a conflict.

_timestamp

protected Time _timestamp

The timestamp of the event.

Constructor Detail

DEEvent

public DEEvent(Actor actor,
               Time timeStamp,
               int microstep,
               int depth)
        throws IllegalActionException

Construct a pure event with the specified destination actor, timestamp, microstep, and depth.

Parameters:

actor - The destination actor

timeStamp - The time when the event occurs.

microstep - The phase of execution within a fixed time.

depth - The topological depth of the destination actor.

Throws:

IllegalActionException - If the actor has a priority parameter, but its value cannot be obtained, which should be an integer.

DEEvent

public DEEvent(IOPort ioPort,
               Time timeStamp,
               int microstep,
               int depth)
        throws IllegalActionException

Construct a trigger event with the specified destination IO port, timestamp, microstep, and depth.

Parameters:

ioPort - The destination IO port.

timeStamp - The time when the event occurs.

microstep - The phase of execution within a fixed time.

depth - The topological depth of the destination IO Port.

Throws:

IllegalActionException - If the actor has a priority parameter, but its value cannot be obtained, which should be an integer.

DEEvent

private DEEvent(Actor actor,
                IOPort ioPort,
                Time timeStamp,
                int microstep,
                int depth)
         throws IllegalActionException

Construct a pure event with the specified destination actor, IO port timestamp, microstep, and depth.

Parameters:

actor - The destination actor

ioPort - The destination IO port.

timeStamp - The time when the event occurs.

microstep - The phase of execution within a fixed time.

depth - The topological depth of the destination actor or the IO port (if not null).

Throws:

IllegalActionException - If the actor has a priority parameter, but its value cannot be obtained, which should be an integer.

Method Detail

actor

public final Actor actor()

Return the destination actor for this event.

Returns:

The destination actor.

compareTo

public final int compareTo(DEEvent event)

Compare the tag and depth of this event with those of the argument event for the order. Return -1, 0, or 1 if this event happens earlier than, the same time as, or later than the argument event.

Their timestamps are compared first. If the two timestamps are not the same, their order defines the events' order. Otherwise, the microsteps of events are compared for the order, where an event with the smaller microstep happens earlier. If the events have the same microstep, their depths are compared. The event with a smaller depth happens earlier. If the two events have the same tag and depth, then they happen at the same time.

Parameters:

event - The event to compare against.

Returns:

-1, 0, or 1, depends on the order of the events.

compareTo

public final int compareTo(java.lang.Object event)

Compare this event with the argument event for an order. See compareTo(DEEvent event) for the comparison rules. The argument event has to be an instance of DEEvent. Otherwise, a ClassCastException will be thrown.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

event - The event to compare against.

Returns:

-1, 0, or 1, depending on the order of the events.

Throws:

java.lang.ClassCastException - If the argument event is not an instance of DEEvent.

depth

public final int depth()

Return the depth of this event. For a pure event, it is the depth of the destination actor in the topological sort. For a trigger event, it is the depth of the destination IO port.

Returns:

The depth of this event.

equals

public boolean equals(java.lang.Object object)

Indicate whether some other object is equal to this DE Event. DEEvents are equal if they are associated with the same actors and compareTo() returns 0;

Overrides:

equals in class java.lang.Object

Parameters:

object - The object with which to compare.

Returns:

true if the object is a DEEvent and the fields of the object and of this object are equal.

See Also:

hashCode()

hasTheSameTagAndDepthAs

public final boolean hasTheSameTagAndDepthAs(DEEvent event)

Return true if this event has the same tag with the specified one, and their depths are the same.

Parameters:

event - The event to compare against.

Returns:

True if this event has the same tag with the specified one, and their depths are the same.

hasTheSameTagAs

public final boolean hasTheSameTagAs(DEEvent event)

Return true if this event has the same tag as the argument DE event.

Parameters:

event - The DE event to compare against.

Returns:

True if this event has the same tag as the specified one.

hashCode

public int hashCode()

Return the hash code for the event object.

Overrides:

hashCode in class java.lang.Object

Returns:

The hash code for the event object.

See Also:

equals(Object)

ioPort

public final IOPort ioPort()

Return the destination IO port of this event. Note that for a pure event, the destination IO Port is null.

Returns:

The destination ioPort.

microstep

public final int microstep()

Return the microstep of this event.

Returns:

The microstep of this event.

timeStamp

public final Time timeStamp()

Return the timestamp.

Returns:

The timestamp.

toString

public java.lang.String toString()

Return a description of the event, including the the tag, depth, and destination information.

Overrides:

toString in class java.lang.Object

Returns:

The token as a string with the time stamp.

_updateDepth

void _updateDepth(int newDepth)

Update the depth of this event if the new depth is no less than 0. Otherwise, do nothing.

Parameters:

newDepth - The new depth for this event.