ptolemy.domains.sdf.kernel

Class SDFReceiver

java.lang.Object

ptolemy.actor.AbstractReceiver

ptolemy.domains.sdf.kernel.SDFReceiver

All Implemented Interfaces:

Receiver

Direct Known Subclasses:

DistributedSDFReceiver, DTReceiver, PthalesReceiver

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$

Author:

Steve Neuendorffer

See Also:

ArrayFIFOQueue

Pt.AcceptedRating:

Green (neuendor)

Pt.ProposedRating:

Green (neuendor)

Field Summary

Fields

Modifier and Type	Field and Description
int	_waitingTokens The number of tokens waiting to be consumed during scheduling.
static int	INFINITE_CAPACITY A constant indicating that the capacity of the receiver is unbounded.

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
void	clear() Clear this receiver of any contained tokens.
java.util.List<Token>	elementList() Return a list with the tokens currently in the receiver, or an empty list if there are no such 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	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, getModelTime, isKnown, putArray, putArrayToAll, putToAll, reset, setContainer, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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

_waitingTokens

public int _waitingTokens

The number of tokens waiting to be consumed during scheduling.

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

elementList

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

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

Specified by:

elementList in interface Receiver

Overrides:

elementList in class AbstractReceiver

Returns:

A list of instances of Token.

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 equal to count.

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.

See Also:

setCapacity(int)

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, or null to not put any token.

Throws:

NoRoomException - If the receiver is full.

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.

See Also:

getCapacity()

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.