se.lth.cs.realtime.event
Class RTEvent

java.lang.Object
  java.util.EventObject
      se.lth.cs.realtime.event.RTEvent

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

AckEvent, ActivityEvent, ExceptionEvent, JPEGEvent, PeriodicEvent, RendezvousEvent, RunnableEvent, TriggerEvent

public class RTEvent

extends java.util.EventObject

The base class of real-time/time-stamped events. Every RTEvent comes from a source object referred to in the EventObject base class. Additional IDs, such as sequential numbers or the kind of event within a certain type, are expected to be defined in subclasses together with other user attributes. The time stamp is, however, fundamental to real-time systems as a mean to denote the freshness of the data. It is therefore an attribute here and the motivation for this class.

The source object, often referring to another thread, is not supposed to keep any reference to the event after posting it. Therefore, methods of this class should not need to be synchronized. To support detection of kept references, for instance when the event is sent again, there is a field owner which is set to the same as source when the event is created, if the source is a thread. If the source is not a thread, the owner is set to be the currently executing (real-time of Java) thread. Since ownership is meaningful within a program only, it is transient and an Activity that is not a thread should not be owner. Specifically, if the source is an instance of ActivityImpl, the represented thread object is set to be the owner.

When an event is transferred, for instance via a buffer, the ownership changes to the buffer and then to the receiving thread. Using available classes, the user should not need to care about the ownership, it is checked to detect certain programming errors. Sometimes, however, it is desirable to keep a set of event objects that are sent several times, for instance every time a certain state transition occurs. In such cases the specific event subclasses are supposed to set the (protected) owner field to null, which disables the checking of ownership. As way of doing that, creating an RTEvent with source specified to be null results in source being set to RTThread.currentThread() and owner is set to null.

There is a ticker attribute referring to a time-base, which can be given to the constructor. This is for special computers or special applications; if you do not know that you need it, simply ignore it and the default System.currentTimeMillis() will be used as the actual ticker. However, obtaining the time via getMillis or getSeconds will make your code portable to such special applications where the ticker is used (e.g. to run an extra instance of a model-based control system ahead of time to draw conclusions about optimal control actions).

See Also:

License, Serialized Form

Constructor Summary

RTEvent()
Constructs an RTEvent object with the current thread as source and a time stamp from the current system time.

RTEvent(long ts)
Constructs an RTEvent object with the current thread as source and with the specified time stamp.

RTEvent(java.lang.Object source)
Constructs an RTEvent object with the specified source object and a time stamp from the current system time.

RTEvent(java.lang.Object source, long ts)
Constructs an RTEvent object with the specified source object and time stamp.

RTEvent(java.lang.Object source, long ts, Timebase timebase)
Constructs an RTEvent object with the specified source object and time-stamp with respect to the specified time-base.

Method Summary

long	getMillis() Returns the event's time stamp in number of milli-seconds.
long	getNanos() Return the sub-milli part of the time-stamp, if any.
java.lang.Object	getOwner() Obtain current owner.
double	getSeconds() Returns the creation-time (or supplied time-stamp= of this event.
long	getTicks() Returns the event's time stamp.
Timebase	getTimebase() Obtains the time-base relating (possibly locally counted) ticks or seconds to real or simulated time.
java.lang.String	toString() Gives a string representation of the event object.

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RTEvent

public RTEvent()

Constructs an RTEvent object with the current thread as source and a time stamp from the current system time.

RTEvent

public RTEvent(java.lang.Object source)

Constructs an RTEvent object with the specified source object and a time stamp from the current system time.

Parameters:

source - The object where the event originated.

RTEvent

public RTEvent(long ts)

Constructs an RTEvent object with the current thread as source and with the specified time stamp.

Parameters:

ts - The time from which the event originates.

RTEvent

public RTEvent(java.lang.Object source,
               long ts)

Constructs an RTEvent object with the specified source object and time stamp.

Parameters:

source - The object where the event originated.

ts - The time from which the event originates.

RTEvent

public RTEvent(java.lang.Object source,
               long ts,
               Timebase timebase)

Constructs an RTEvent object with the specified source object and time-stamp with respect to the specified time-base.

Parameters:

source - The object where the event originated.

ts - The time from which the event originates.

timebase - The base of time in which the time stamp is expressed.

Method Detail

getOwner

public final java.lang.Object getOwner()

Obtain current owner. Mainly useful for debugging.

Returns:

the object which is currently the owner of this event.

getTicks

public long getTicks()

Returns the event's time stamp. Use the other get-time methods to make the management of time portable, e.g. getSeconds().

Returns:

the time in number of (system dependent) ticks.

getSeconds

public double getSeconds()

Returns the creation-time (or supplied time-stamp= of this event.

Returns:

the time-stamp expressed in seconds.

getMillis

public long getMillis()

Returns the event's time stamp in number of milli-seconds. The returned value is compliant with System.currentTimeMillis().

Returns:

the time-stamp expressed in milli-seconds.

getNanos

public long getNanos()

Return the sub-milli part of the time-stamp, if any. If permitted by numerical accuracy, using getSeconds usually is a better alternative when working with times that contain fractions of milli-seconds.

Returns:

any nano-second part of time-stamp.

getTimebase

public Timebase getTimebase()

Obtains the time-base relating (possibly locally counted) ticks or seconds to real or simulated time.

Returns:

the time-base, or null if System.currentTimeMillis is used.

toString

public java.lang.String toString()

Gives a string representation of the event object.

The string is of the form:

ClassName[paramString]

where ClassName is the name of the event class, paramString is the string returned by paramString.