ptolemy.domains.dde.kernel

Class PrioritizedTimedQueue

java.lang.Object

ptolemy.actor.AbstractReceiver

ptolemy.domains.dde.kernel.PrioritizedTimedQueue

All Implemented Interfaces:

Receiver

Direct Known Subclasses:

DDEReceiver

public class PrioritizedTimedQueue
extends AbstractReceiver

A FIFO queue with time and priority attributes that is used for storing tokens with time stamps. A "time stamp" is a time value that is associated with a token and is used to order the consumption of a token with respect to other time stamped tokens. To help organize the tokens contained by this queue, two flags are maintained: last time and receiver time. The last time flag is defined to be equivalent to the time stamp of the token that was most recently placed in the queue. The receiver time flag is defined as the time stamp of the oldest token in the queue or the last token to be removed from the queue if the queue is empty. Both of these flags must have monotonically, non-decreasing values (with the exception of the IGNORE, INACTIVE and ETERNITY values). At the conclusion of a simulation run the receiver time is set to INACTIVE.

A PrioritizedTimedQueue is subclassed by DDEReceiver. Hence, PrioritizedTimedQueues serve as the foundation for receivers contained in the IO ports of actors operating within DDE models. A TimeKeeper object is assigned to each actor that operates according to the DDE model of computation. The TimeKeeper manages each of the receivers that are contained by an actor by keeping track of the receiver times of each receiver. As information flows through a PrioritizedTimedQueue, the TimeKeeper must be kept up to date with respect to the receiver times. The TimeKeeper orders the PrioritizedTimedQueues according to their receiver times and priorities. PrioritizedTimedQueues with smaller receiver times are ordered first.

PrioritizedTimedQueues with identical receiver times are sorted according to their respective priorities. PrioritizedTimedQueues are assigned priorities (a nonnegative integer) by a TimeKeeper when the TimeKeeper is instantiated. Receivers with higher receiver priorities are ordered before receivers with lower priorities. The priority of a receiver can be explicitly specified or it can be implicitly determined based on the topology. In the latter case, the priority of a receiver is set according to the inverse order in which it was 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.

If the oldest token in the queue has a time stamp of IGNORE, then the next oldest token from the other receivers contained by the actor in question will be consumed and the token time stamped IGNORE will be dropped. The IGNORE time stamp is useful in feedback topologies in which an actor should ignore inputs from a feedback cycle when the execution of the model is just beginning. FeedBackDelay actors output a single IGNORE token during their initialize() methods for just this reason. In general, IGNORE tokens should not be handled unless fundamental changes to the DDE kernel are intended.

The values of the package friendly variables IGNORE, INACTIVE and ETERNITY are arbitrary as long as they have unique, negative values. ETERNITY is used in conjunction with the completionTime to indicate that an actor should continue executing indefinitely.

Note that a PrioritizedTimedQueue is intended for use within a multi-threaded environment. PrioritizedTimedQueue does not require the synchronization facilities provided by ptolemy.kernel.util.Workspace. PrioritizedTimedQueue is subclassed by DDEReceiver which adds significant synchronization facilities and where appropriate employs workspace.

Since:

Ptolemy II 0.4

Version:

$Id$

Author:

John S. Davis II

See Also:

DDEReceiver, TimeKeeper

Pt.AcceptedRating:

Green (kienhuis)

Pt.ProposedRating:

Green (davisj)

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Time	_lastTime
(package private) int	_priority
(package private) static double	ETERNITY
(package private) static double	IGNORE
(package private) static double	INACTIVE

Constructor Summary

Constructors

Constructor and Description
PrioritizedTimedQueue() Construct an empty queue with no container.
PrioritizedTimedQueue(IOPort container) Construct an empty queue with the specified IOPort container.
PrioritizedTimedQueue(IOPort container, int priority) Construct an empty queue with the specified IOPort container and priority.

Method Summary

Modifier and Type	Method and Description
(package private) Time	_getCompletionTime() Return the completion time of this receiver.
(package private) boolean	_hasNullToken() Return true if this receiver has a NullToken at the front of the queue; return false otherwise.
(package private) void	_setCompletionTime(Time time) Set the completion time of this receiver.
(package private) void	_setReceiverTime(Time time) Set the receiver time of this receiver to the specified value.
java.util.List<Token>	elementList() Return a list with the tokens currently in the receiver, or an empty list if there is no such token.
Token	get() Take the the oldest token off of the queue and return it.
int	getCapacity() Get the queue capacity of this receiver.
Time	getLastTime() Deprecated. Only used for testing purposes
Time	getReceiverTime() Return the receiver time of this receiver.
boolean	hasRoom() Return true if the number of tokens stored in the queue is less than the capacity of the queue.
boolean	hasRoom(int numberOfTokens) Return true if the queue capacity minus the queue size is greater than the argument.
boolean	hasToken() Return true if there are tokens stored on the queue.
boolean	hasToken(int numberOfTokens) Return true if queue size is at least the argument.
void	put(Token token) Throw an exception, since this method is not used in DDE.
void	put(Token token, Time time) Put a token on the queue with the specified time stamp and set the last time value to be equal to this time stamp.
void	removeIgnoredToken() Remove the oldest token off of this queue if it has a time stamp with a value of IGNORE.
void	reset() Reset local flags.
void	setCapacity(int capacity) Set the queue capacity of this receiver.

Methods inherited from class ptolemy.actor.AbstractReceiver

clear, getArray, getContainer, getCurrentTime, getModelTime, isKnown, putArray, putArrayToAll, putToAll, setContainer, toString

Methods inherited from class java.lang.Object

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

Field Detail

ETERNITY

static final double ETERNITY

See Also:

Constant Field Values

IGNORE

static final double IGNORE

See Also:

Constant Field Values

INACTIVE

static final double INACTIVE

See Also:

Constant Field Values

_lastTime

Time _lastTime

_priority

int _priority

Constructor Detail

PrioritizedTimedQueue

public PrioritizedTimedQueue()

Construct an empty queue with no container.

PrioritizedTimedQueue

public PrioritizedTimedQueue(IOPort container)
                      throws IllegalActionException

Construct an empty queue with the specified IOPort container.

Parameters:

container - The IOPort that contains this receiver.

Throws:

IllegalActionException - If this receiver cannot be contained by the proposed container.

PrioritizedTimedQueue

public PrioritizedTimedQueue(IOPort container,
                             int priority)
                      throws IllegalActionException

Construct an empty queue with the specified IOPort container and priority.

Parameters:

container - The IOPort that contains this receiver.

priority - The priority of this receiver.

Throws:

IllegalActionException - If this receiver cannot be contained by the proposed container.

Method Detail

elementList

public java.util.List<Token> elementList()

Return a list with the tokens currently in the receiver, or an empty list if there is no such token.

Specified by:

elementList in interface Receiver

Overrides:

elementList in class AbstractReceiver

Returns:

A list of instances of Token.

get

public Token get()

Take the the oldest token off of the queue and return it. If the queue is empty, throw a NoTokenException. If there are other tokens left on the queue after this removal, then set the receiver time of this receiver to equal that of the next oldest token. Update the TimeKeeper that manages this PrioritizedTimedQueue. If there are any receivers in the TimeKeeper with receiver times of PrioritizedTimedQueue.IGNORE, remove the first token from these receivers.

Specified by:

get in interface Receiver

Specified by:

get in class AbstractReceiver

Returns:

The oldest token off of the queue.

Throws:

NoTokenException - If the queue is empty.

getCapacity

public int getCapacity()

Get the queue capacity of this receiver.

Returns:

The capacity of this receiver's queue.

See Also:

setCapacity(int)

getLastTime

@Deprecated
public Time getLastTime()

Deprecated. Only used for testing purposes

Return the last time of this receiver. This method is not synchronized so the caller should be.

Returns:

The last time.

getReceiverTime

public Time getReceiverTime()

Return the receiver time of this receiver. The receiver time is the time stamp associated with the oldest token that is currently on the queue. If the queue is empty, then the receiver time value is equal to the "last time."

Returns:

The receiver time of this PrioritizedTimedQueue.

hasRoom

public boolean hasRoom()

Return true if the number of tokens stored in the queue is less than the capacity of the queue. Return false otherwise.

Specified by:

hasRoom in interface Receiver

Specified by:

hasRoom in class AbstractReceiver

Returns:

True if the queue is not full; return false otherwise.

hasRoom

public boolean hasRoom(int numberOfTokens)
                throws java.lang.IllegalArgumentException

Return true if the queue capacity minus the queue size is greater than the argument.

Specified by:

hasRoom in interface Receiver

Specified by:

hasRoom in class AbstractReceiver

Parameters:

numberOfTokens - The number of tokens to put into the queue.

Returns:

True if the queue is not full; return false otherwise.

Throws:

java.lang.IllegalArgumentException - If the argument is not positive. This is a runtime exception, so it does not need to be declared explicitly.

hasToken

public boolean hasToken()

Return true if there are tokens stored on the queue. Return false if the queue is empty.

Specified by:

hasToken in interface Receiver

Specified by:

hasToken in class AbstractReceiver

Returns:

True if the queue is not empty; return false otherwise.

hasToken

public boolean hasToken(int numberOfTokens)
                 throws java.lang.IllegalArgumentException

Return true if queue size is at least the argument.

Specified by:

hasToken in interface Receiver

Specified by:

hasToken in class AbstractReceiver

Parameters:

numberOfTokens - The number of tokens to get from the queue.

Returns:

True if the queue has enough tokens.

Throws:

java.lang.IllegalArgumentException - If the argument is not positive. This is a runtime exception, so it does not need to be declared explicitly.

put

public void put(Token token)

Throw an exception, since this method is not used in DDE.

Specified by:

put in interface Receiver

Specified by:

put in class AbstractReceiver

Parameters:

token - The token to be put to the receiver.

Throws:

NoRoomException - If the receiver is full.

put

public void put(Token token,
                Time time)
         throws NoRoomException

Put a token on the queue with the specified time stamp and set the last time value to be equal to this time stamp. If the queue is empty immediately prior to putting the token on the queue, then set the receiver time value to be equal to the last time value. If the queue is full, throw a NoRoomException. Time stamps can not be set to negative values that are not equal to IGNORE or INACTIVE; otherwise an IllegalArgumentException will be thrown.

Parameters:

token - The token to put on the queue.

time - The time stamp of the token.

Throws:

NoRoomException - If the queue is full.

removeIgnoredToken

public void removeIgnoredToken()

Remove the oldest token off of this queue if it has a time stamp with a value of IGNORE. Reset the receiver time and update the time keeper's receiver list.

Throws:

NoTokenException - If the queue is empty.

reset

public void reset()

Reset local flags. The local flags of this receiver impact the local notion of time of the actor that contains this receiver. This method is not synchronized so the caller should be.

Specified by:

reset in interface Receiver

Overrides:

reset in class AbstractReceiver

setCapacity

public void setCapacity(int capacity)
                 throws IllegalActionException

Set the queue capacity of this receiver.

Parameters:

capacity - The capacity of this receiver's queue.

Throws:

IllegalActionException - If the superclass throws it.

See Also:

getCapacity()

_getCompletionTime

Time _getCompletionTime()

Return the completion time of this receiver. This method is not synchronized so the caller should be.

Returns:

The completion time.

_hasNullToken

boolean _hasNullToken()

Return true if this receiver has a NullToken at the front of the queue; return false otherwise. This method is not synchronized so the caller should be.

Returns:

True if this receiver contains a NullToken in the oldest queue position; return false otherwise.

_setCompletionTime

void _setCompletionTime(Time time)

Set the completion time of this receiver. If the completion time argument is negative but is not equal to PrioritizedTimedQueue.ETERNITY, then throw an IllegalArgumentException. This method is not synchronized so the caller should be.

Parameters:

time - The completion time of this receiver.

_setReceiverTime

void _setReceiverTime(Time time)

Set the receiver time of this receiver to the specified value. If this queue is not empty, then the receiver time will not be set to the specified value. This method is not synchronized so the caller should be.

Parameters:

time - The new receiver time.