ptolemy.domains.sdf.kernel
Class SDFReceiver

java.lang.Object
  extended byptolemy.actor.AbstractReceiver
      extended byptolemy.domains.sdf.kernel.SDFReceiver
All Implemented Interfaces:
Receiver
Direct Known Subclasses:
DTReceiver

public class SDFReceiver
extends AbstractReceiver

A first-in, first-out (FIFO) queue receiver with variable capacity and optional history. Tokens are put into the receiver with the put() method, and removed from the receiver with the get() method. The token removed is the one placed in the receiver before any other (i.e. the "oldest", although this has nothing to do with time in the model. By default, the capacity is unbounded, but it can be set to any nonnegative size. If the history capacity is greater than zero (or infinite, indicated by a capacity of INFINITE_CAPACITY), then tokens removed from the receiver are stored in a history queue rather than simply removed. By default, the history capacity is zero.

Since:
Ptolemy II 0.2
Version:
$Id: SDFReceiver.java,v 1.51 2004/04/13 05:12:36 cxh Exp $
Author:
Steve Neuendorffer
See Also:
ArrayFIFOQueue
Accepted Rating:
Green (neuendor)
Proposed Rating:
Green (neuendor)

Field Summary
static int INFINITE_CAPACITY
          A constant indicating that the capacity of the receiver is unbounded.
 
Constructor Summary
SDFReceiver()
          Construct an empty receiver with no container.
SDFReceiver(int size)
          Construct an empty receiver with no container and given size.
SDFReceiver(IOPort container)
          Construct an empty receiver with the specified container.
SDFReceiver(IOPort container, int size)
          Construct an empty receiver with the specified container and size.
 
Method Summary
 void clear()
          Clear this receiver of any contained tokens.
 Token get()
          Remove the first token (the oldest one) from the receiver and return it.
 Token get(int offset)
          Return a token in the receiver or its history.
 Token[] getArray(int count)
          Get an array of tokens from this receiver.
 int getCapacity()
          Return the capacity, or INFINITE_CAPACITY if it is unbounded.
 int getHistoryCapacity()
          Return the capacity of the history queue.
 boolean hasRoom()
          Return true if put() will succeed in accepting a token.
 boolean hasRoom(int tokens)
          Return true if put() will succeed in accepting the specified number of tokens.
 boolean hasToken()
          Return true if get() will succeed in returning a token.
 boolean hasToken(int tokens)
          Return true if get() will succeed in returning a token the given number of times.
 java.util.Enumeration historyElements()
          Enumerate the tokens stored in the history queue, which are the N most recent tokens taken from the receiver, beginning with the oldest, where N is less than or equal to the history capacity.
 int historySize()
          Return the number of tokens in history.
 void put(Token token)
          Put a token to the receiver.
 void putArray(Token[] token, int count)
          Put a specified number of token from an array into the receiver.
 void setCapacity(int capacity)
          Set receiver capacity.
 void setHistoryCapacity(int capacity)
          Set the capacity of the history queue.
 int size()
          Return the number of tokens in the receiver.
 
Methods inherited from class ptolemy.actor.AbstractReceiver
getContainer, getCurrentTime, isKnown, setContainer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INFINITE_CAPACITY

public static final int INFINITE_CAPACITY
A constant indicating that the capacity of the receiver is unbounded.

See Also:
Constant Field Values
Constructor Detail

SDFReceiver

public SDFReceiver()
Construct an empty receiver with no container.


SDFReceiver

public SDFReceiver(int size)
Construct an empty receiver with no container and given size.

Parameters:
size - The size of the queue in the receiver.

SDFReceiver

public SDFReceiver(IOPort container)
            throws IllegalActionException
Construct an empty receiver with the specified container.

Parameters:
container - The container of the receiver.
Throws:
IllegalActionException - If the container does not accept this receiver.

SDFReceiver

public SDFReceiver(IOPort container,
                   int size)
            throws IllegalActionException
Construct an empty receiver with the specified container and size.

Parameters:
container - The container of the receiver.
size - The size of the queue in the receiver.
Throws:
IllegalActionException - If the container does not accept this receiver.
Method Detail

clear

public void clear()
Clear this receiver of any contained tokens.

Specified by:
clear in interface Receiver
Overrides:
clear in class AbstractReceiver

get

public Token get()
Remove the first token (the oldest one) from the receiver and return it. If there is no token in the receiver, throw an exception.

Specified by:
get in interface Receiver
Specified by:
get in class AbstractReceiver
Returns:
The oldest token in the receiver.
Throws:
NoTokenException - If there is no token in the receiver.

get

public Token get(int offset)
Return a token in the receiver or its history. If the offset argument is zero, return the oldest token in the receiver. If the offset is 1, return the second oldest token, etc. The token is not removed from the receiver. If there is no such token in the receiver (the offset is greater than or equal to the number of tokens currently in the receiver), throw an exception. If the offset is -1, return the most recent token removed from the receiver. If it is -2, return the second most recent token removed from the receiver, etc. If there is no such token in the receiver's history (the history capacity is zero or the absolute value of offset is greater than the number of tokens currently in the receiver's history), an exception is thrown.

Parameters:
offset - The offset from the oldest token in the receiver.
Returns:
The token at the desired offset in the receiver or its history.
Throws:
NoTokenException - If the offset is out of range.

getArray

public Token[] getArray(int count)
Get an array of tokens from this receiver. The parameter specifies the number of valid tokens to get in the returned array. The length of the returned array will be at least equal to count. This method may sometimes return an array with length greater than count, in which case, only the first count elements are valid. This behavior is allowed so that this method can choose to reallocate the returned token array only when the vector length is increased.

Specified by:
getArray in interface Receiver
Overrides:
getArray in class AbstractReceiver
Parameters:
count - The number of valid tokens to get in the returned array.
Returns:
An array containing count tokens from the receiver.
Throws:
NoTokenException - If there are not count tokens.

getCapacity

public int getCapacity()
Return the capacity, or INFINITE_CAPACITY if it is unbounded.

Returns:
The capacity of the receiver.

getHistoryCapacity

public int getHistoryCapacity()
Return the capacity of the history queue. This will be zero if the history mechanism is disabled and INFINITE_CAPACITY if the history capacity is unbounded.

Returns:
The capacity of the history queue.
See Also:
historyElements(), historySize(), setHistoryCapacity(int)

hasRoom

public boolean hasRoom()
Return true if put() will succeed in accepting a token.

Specified by:
hasRoom in interface Receiver
Specified by:
hasRoom in class AbstractReceiver
Returns:
A boolean indicating whether a token can be put in this receiver.

hasRoom

public boolean hasRoom(int tokens)
                throws java.lang.IllegalArgumentException
Return true if put() will succeed in accepting the specified number of tokens.

Specified by:
hasRoom in interface Receiver
Specified by:
hasRoom in class AbstractReceiver
Parameters:
tokens - The number of tokens.
Returns:
A boolean indicating whether a token can be put in this receiver.
Throws:
java.lang.IllegalArgumentException - If the argument is less than one. This is a runtime exception, so it need not be declared explicitly by the caller.

hasToken

public boolean hasToken()
Return true if get() will succeed in returning a token.

Specified by:
hasToken in interface Receiver
Specified by:
hasToken in class AbstractReceiver
Returns:
A boolean indicating whether there is a token in this receiver.

hasToken

public boolean hasToken(int tokens)
                 throws java.lang.IllegalArgumentException
Return true if get() will succeed in returning a token the given number of times.

Specified by:
hasToken in interface Receiver
Specified by:
hasToken in class AbstractReceiver
Parameters:
tokens - The number of tokens.
Returns:
A boolean indicating whether there are the given number of tokens in this receiver.
Throws:
java.lang.IllegalArgumentException - If the argument is less than one. This is a runtime exception, so it need not be declared explicitly by the caller.

historyElements

public java.util.Enumeration historyElements()
Enumerate the tokens stored in the history queue, which are the N most recent tokens taken from the receiver, beginning with the oldest, where N is less than or equal to the history capacity. If the history capacity is INFINITE_CAPACITY, then the enumeration includes all tokens previously taken from the receiver. If the history capacity is zero, then return an empty enumeration.

Returns:
An enumeration of tokens.
See Also:
getHistoryCapacity(), historySize(), setHistoryCapacity(int)

historySize

public int historySize()
Return the number of tokens in history.

Returns:
The number of tokens in history.
See Also:
getHistoryCapacity(), historyElements(), setHistoryCapacity(int)

put

public void put(Token token)
Put a token to the receiver. If the receiver is full, throw an exception.

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.

putArray

public void putArray(Token[] token,
                     int count)
Put a specified number of token from an array into the receiver. If the receiver has insufficient room, throw an exception, and add none of the tokens to the receiver. An exception is thrown if count is greater than the length of the token array.

Specified by:
putArray in interface Receiver
Overrides:
putArray in class AbstractReceiver
Parameters:
token - The token array that contains tokens to be put into the receiver.
count - The number of tokens from token to put in the receiver. This should be less than the length of token.
Throws:
NoRoomException - If the receiver is full.
IndexOutOfBoundException - If the array does not contain at least count elements.

setCapacity

public void setCapacity(int capacity)
                 throws IllegalActionException
Set receiver capacity. Use INFINITE_CAPACITY to indicate unbounded capacity (which is the default). If the number of tokens currently in the receiver exceeds the desired capacity, throw an exception.

Parameters:
capacity - The desired receiver capacity.
Throws:
IllegalActionException - If the receiver has more tokens than the proposed capacity or the proposed capacity is illegal.

setHistoryCapacity

public void setHistoryCapacity(int capacity)
                        throws IllegalActionException
Set the capacity of the history queue. Use 0 to disable the history mechanism and INFINITE_CAPACITY to make the history capacity unbounded. If the size of the history queue exceeds the desired capacity, then remove the oldest tokens from the history queue until its size equals the proposed capacity. Note that this can be used to clear the history queue by supplying 0 as the argument.

Parameters:
capacity - The desired history capacity.
Throws:
IllegalActionException - If the desired capacity is illegal.
See Also:
getHistoryCapacity(), historyElements(), historySize()

size

public int size()
Return the number of tokens in the receiver.

Returns:
The number of tokens in the receiver.