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)

Constructor Summary

Constructors
Constructor	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

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`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

- 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()

Class PrioritizedTimedQueue

Constructor Summary

Method Summary

Methods inherited from class ptolemy.actor.AbstractReceiver

Methods inherited from class java.lang.Object

Constructor Detail

PrioritizedTimedQueue

PrioritizedTimedQueue

PrioritizedTimedQueue

Method Detail

elementList

get

getCapacity

getLastTime

getReceiverTime

hasRoom

hasRoom

hasToken

hasToken

put

put

removeIgnoredToken

reset

setCapacity