ptolemy.domains.dde.kernel
Class TimeKeeper

java.lang.Object
  ptolemy.domains.dde.kernel.TimeKeeper

public class TimeKeeper
extends java.lang.Object

A TimeKeeper manages an actor's local value of time in the DDE domain. A TimeKeeper is instantiated by a DDEThread and is used by the thread to manage time for the thread's actor. A TimeKeeper has a list of DDEReceivers that are contained by the actor that the thread controls. As tokens flow through the DDEReceivers, the TimeKeeper keeps track of the advancement of time local to the actor.

DDEReceivers each have three important variables: receiver time, last time and priority. The receiver time of a DDEReceiver is equal to the time of the oldest event that resides in the receiver. The last time is equal to the time of the newest event residing on the receiver.

A TimeKeeper manages the DDEReceivers of its actor by keeping track of the receiver with the minimum receiver time. The actor is allowed to consume a token from a receiver if that receiver has the unique, minimum receiver time of all receivers managed by the TimeKeeper. The TimeKeeper keeps track of its receivers' priorities as well. The receiver with the highest priority is enabled to have its token consumed if the receiver shares a common minimum receive time with one or more additional receivers.

The receiver priorities are set using the method _setReceiverPriorities() in the following manner. All of the input receivers associated with a given TimeKeeper are prioritized according to the inverse order in which they were connected in the model topology. I.e., if two input receivers (rA and rB) of an actor are connected such that receiver rA is connected before receiver rB, then rB will have a higher priority than rA.

The above approach provides each receiver associated with a given TimeKeeper with a unique priority, such that the set of receiver priorities of the associated TimeKeeper is totally ordered.

A TimeKeeper manages the ordering of receivers by keeping track of its receivers and their corresponding receiver times and priorities. As tokens are placed in and taken out of the receivers of an actor, the TimeKeeper's receiver list is updated. The receiver list is sorted by ReceiverComparator. This same information allows the TimeKeeper to determine what the current time is local to the actor.

Since:

Ptolemy II 0.3

Version:

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

Author:

John S. Davis II

See Also:

DDEThread

Accepted Rating:

Green (kienhuis)

Proposed Rating:

Green (davisj)

Field Summary

private Actor	_actor
private Time	_currentTime
(package private) boolean	_ignoredReceivers
private Time	_outputTime
private ReceiverComparator	_receiverComparator
private java.util.LinkedList	_receiverList

Constructor Summary

TimeKeeper(Actor actor)
Construct a time keeper to manage the local time of an actor in the DDE domain.

Method Summary

(package private) void	_setOutputTime(Time outputTime) Set the output time associated with this time keeper.
(package private) void	_setReceiverPriorities() Set the priorities of the receivers contained in the input ports of the actor managed by this time keeper.
double	getCurrentTime() Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()
PrioritizedTimedQueue	getFirstReceiver() Return the active PrioritizedTimedQueue with the oldest receiver time of all receivers contained in the actor that this TimeKeeper controls.
Time	getModelTime() Return the current time of this TimeKeeper.
Time	getNextTime() Return the earliest possible time stamp of the next token to be consumed by the actor managed by this time keeper.
Time	getOutputTime() Return the current value of the output time associated with this time keeper and, after so doing, set the output time to a new value that is equivalent to this time keeper's current time.
void	removeAllIgnoreTokens() Update receivers controlled by this time keeper that have a receiver time equal to PrioritizedTimedQueue.IGNORE.
void	sendOutNullTokens(DDEReceiver receiver) Send a NullToken to all output channels that have a receiver time less than or equal to the current time of this time keeper.
void	setCurrentTime(Time time) Set the current time of this TimeKeeper.
void	updateReceiverList(PrioritizedTimedQueue prioritizedTimedQueue) Update the list of receivers by adding a receiver to the receiver list if not already present and then sorting the list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_actor

private Actor _actor

_currentTime

private Time _currentTime

_outputTime

private Time _outputTime

_ignoredReceivers

volatile boolean _ignoredReceivers

_receiverComparator

private ReceiverComparator _receiverComparator

_receiverList

private java.util.LinkedList _receiverList

Constructor Detail

TimeKeeper

public TimeKeeper(Actor actor)
           throws IllegalActionException

Construct a time keeper to manage the local time of an actor in the DDE domain. Set the receiver priorities of all receivers contained by the actor of this time keeper.

Parameters:

actor - The DDEActor for which time will be managed.

Throws:

IllegalActionException - If there is an error while setting the receiver priorities.

Method Detail

getCurrentTime

public double getCurrentTime()

Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()

Return the current time of this TimeKeeper. The current time is equal to the time stamp associated with the token most recently consumed by one of the receivers managed by this TimeKeeper.

Returns:

The current time of this TimeKeeper.

See Also:

setCurrentTime(Time)

getFirstReceiver

public PrioritizedTimedQueue getFirstReceiver()

Return the active PrioritizedTimedQueue with the oldest receiver time of all receivers contained in the actor that this TimeKeeper controls. A PrioritizedTimedQueue is considered active if its receiver time is nonnegative. If all receivers of the managed actor are no longer active, then return the first receiver to become inactive.

Returns:

PrioritizedTimedQueue The oldest active PrioritizedTimedQueue managed by this TimeKeeper.

getModelTime

public Time getModelTime()

Return the current time of this TimeKeeper. The current time is equal to the time stamp associated with the token most recently consumed by one of the receivers managed by this TimeKeeper.

Returns:

The current time of this TimeKeeper.

getNextTime

public Time getNextTime()

Return the earliest possible time stamp of the next token to be consumed by the actor managed by this time keeper. Consider this returned time value as a greatest lower bound. The next time is equal to the oldest (smallest valued) receiver time of all receivers managed by this thread.

Returns:

The next earliest possible time stamp to be produced by this actor.

getOutputTime

public Time getOutputTime()

Return the current value of the output time associated with this time keeper and, after so doing, set the output time to a new value that is equivalent to this time keeper's current time.

Returns:

double The output time of this time keeper.

removeAllIgnoreTokens

public void removeAllIgnoreTokens()

Update receivers controlled by this time keeper that have a receiver time equal to PrioritizedTimedQueue.IGNORE. For each such receiver, call DDEReceiver.removeIgnoredToken().

sendOutNullTokens

public void sendOutNullTokens(DDEReceiver receiver)

Send a NullToken to all output channels that have a receiver time less than or equal to the current time of this time keeper. In this case, set the time stamp of the NullTokens to be equal to the current time of this time keeper. This method assumes that the actor controlled by this time keeper is atomic.

This method is not synchronized so the calling method should be.

Parameters:

receiver - The receiver that is causing this method to be invoked.

Throws:

IllegalActionException

setCurrentTime

public void setCurrentTime(Time time)

Set the current time of this TimeKeeper. If the specified time is less than the previous value for current time, then throw an IllegalArgumentException. Do not throw an IllegalArgumentException if the current time is set to PrioritizedTimedQueue.INACTIVE to indicate termination.

Parameters:

time - The new value for current time.

Throws:

java.lang.IllegalArgumentException - If there is an attempt to decrease the value of current time to a nonnegative number.

See Also:

getCurrentTime(), getModelTime()

updateReceiverList

public void updateReceiverList(PrioritizedTimedQueue prioritizedTimedQueue)

Update the list of receivers by adding a receiver to the receiver list if not already present and then sorting the list. The receiver list is sorted according to a ReceiverComparator.

Parameters:

prioritizedTimedQueue - The PrioritizedTimedQueue whose position is being updated.

See Also:

ReceiverComparator

_setOutputTime

void _setOutputTime(Time outputTime)
              throws IllegalActionException

Set the output time associated with this time keeper.

Parameters:

outputTime - The output time of this time keeper.

Throws:

IllegalActionException - If the output time is less than the current time.

_setReceiverPriorities

void _setReceiverPriorities()
                      throws IllegalActionException

Set the priorities of the receivers contained in the input ports of the actor managed by this time keeper. Order the receiver priorities relative to one another according to the inverse order in which they were connected to the model topology. I.e., if two input receivers (receiver A and receiver B) are added to an actor such that receiver A is connected in the model topology before receiver B, then receiver B will have a higher priority than receiver A.

Throws:

IllegalActionException - If an error occurs during receiver access.