ptolemy.actor

Class QueueReceiver

java.lang.Object

ptolemy.actor.AbstractReceiver

ptolemy.actor.QueueReceiver

All Implemented Interfaces:

Receiver

Direct Known Subclasses:

PNQueueReceiver

public class QueueReceiver
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 oldest one in the receiver. 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:

Edward A. Lee, Lukito Muliadi, Xiaojun Liu

See Also:

FIFOQueue

Pt.AcceptedRating:

Green (liuj)

Pt.ProposedRating:

Green (eal)

Field Summary

Fields

Modifier and Type	Field and Description
protected FIFOQueue	_queue This is the queue in which data is stored.
static int	INFINITE_CAPACITY Used to indicate that the size of this queue receiver is infinite.

Constructor Summary

Constructors

Constructor and Description
QueueReceiver() Construct an empty receiver with no container.
QueueReceiver(IOPort container) Construct an empty receiver with the specified container.

Method Summary

Modifier and Type	Method and Description
void	clear() Clear this receiver of any contained tokens.
java.util.List<Token>	elementList() List the tokens in the receiver, beginning with the oldest.
java.util.Enumeration	elements() Deprecated. Used elementList() instead.
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.
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 the next call to put() will succeed without a NoRoomException.
boolean	hasRoom(int numberOfTokens) Return true if the queue has room to put the given number of tokens into it (via the put() method).
boolean	hasToken() Return true if the next call to get() will succeed without a a NoTokenException.
boolean	hasToken(int numberOfTokens) Return true if the specified number of tokens is available in the queue.
java.util.List	historyElementList() Deprecated. Used historyElementList() instead.
java.util.Enumeration	historyElements() Deprecated. Used historyElementList() instead.
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

getArray, 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

Used to indicate that the size of this queue receiver is infinite.

See Also:

Constant Field Values

_queue

protected FIFOQueue _queue

This is the queue in which data is stored.

Constructor Detail

QueueReceiver

public QueueReceiver()

Construct an empty receiver with no container.

QueueReceiver

public QueueReceiver(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.

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

List the tokens in the receiver, beginning with the oldest.

Specified by:

elementList in interface Receiver

Overrides:

elementList in class AbstractReceiver

Returns:

An enumeration of tokens.

elements

@Deprecated
public java.util.Enumeration elements()

Deprecated. Used elementList() instead.

Enumerate the tokens in the receiver, beginning with the oldest.

Returns:

An enumeration of tokens.

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.

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:

setHistoryCapacity(int)

hasRoom

public boolean hasRoom()

Return true if the next call to put() will succeed without a NoRoomException.

Specified by:

hasRoom in interface Receiver

Specified by:

hasRoom in class AbstractReceiver

Returns:

True if the queue has room for one more token.

hasRoom

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

Return true if the queue has room to put the given number of tokens into it (via the put() method).

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 has room for the specified number of tokens.

Throws:

java.lang.IllegalArgumentException - If the number of tokens is less than one. This is a runtime exception, and hence does not need to be explicitly declared by the caller.

hasToken

public boolean hasToken()

Return true if the next call to get() will succeed without a a NoTokenException.

Specified by:

hasToken in interface Receiver

Specified by:

hasToken in class AbstractReceiver

Returns:

True if the queue has at least one token in it.

hasToken

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

Return true if the specified number of tokens is available in the queue.

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 specified number of tokens is available.

Throws:

java.lang.IllegalArgumentException - If the number of tokens is less than one. This is a runtime exception, and hence does not need to be explicitly declared by the caller.

historyElementList

@Deprecated
public java.util.List historyElementList()

Deprecated. Used historyElementList() instead.

List 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.

historyElements

@Deprecated
public java.util.Enumeration historyElements()

Deprecated. Used historyElementList() instead.

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.

historySize

public int historySize()

Return the number of tokens in history.

Returns:

The number of tokens in history.

put

public void put(Token token)

Put a token to the receiver. If the receiver is full, throw an exception. If the argument is null, do nothing.

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.

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

size

public int size()

Return the number of tokens in the receiver.

Returns:

The number of tokens in the receiver.