ptolemy.actor

Class AbstractReceiver

java.lang.Object

ptolemy.actor.AbstractReceiver

All Implemented Interfaces:

Receiver

Direct Known Subclasses:

AlgebraicLoopReceiver, CIReceiver, CSPReceiver, DEReceiver, DistributedReceiver, FixedPointReceiver, FSMReceiver, GiottoReceiver, IntermediateReceiver, Mailbox, PrioritizedTimedQueue, QueueReceiver, RendezvousReceiver, SDFReceiver, TDLReceiver, TMReceiver

public abstract class AbstractReceiver
extends java.lang.Object
implements Receiver

An abstract implementation of the Receiver interface. The container methods and some of the more esoteric methods are implemented, while the most domain-specific methods are left undefined. Note that the NoTokenException and NoRoomException exceptions that are thrown by several of the methods are runtime exceptions, so they need not be declared explicitly by the caller.

Since:

Ptolemy II 1.0

Version:

$Id$

Author:

Steve Neuendorffer

See Also:

Receiver

Pt.AcceptedRating:

Green (bart)

Pt.ProposedRating:

Green (eal)

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	clear() Throw an exception.
java.util.List<Token>	elementList() Return a list with tokens that are currently in the receiver available for get() or getArray().
abstract Token	get() Get a token from this receiver.
Token[]	getArray(int numberOfTokens) Get an array of tokens from this receiver.
IOPort	getContainer() Return the container of this receiver, or null if there is none.
double	getCurrentTime() Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()
Time	getModelTime() Return the current time associated with this receiver.
abstract boolean	hasRoom() Return true if the receiver has room to put a token into it (via the put() method).
abstract boolean	hasRoom(int numberOfTokens) Return true if the receiver has room to put the specified number of tokens into it (via the put() method).
abstract boolean	hasToken() Return true if the receiver contains a token that can be obtained by calling the get() method.
abstract boolean	hasToken(int numberOfTokens) Return true if the receiver contains the specified number of tokens.
boolean	isKnown() Return true.
abstract void	put(Token token) Put the specified token into this receiver.
void	putArray(Token[] tokenArray, int numberOfTokens) Put a portion of the specified token array into this receiver.
void	putArrayToAll(Token[] tokens, int numberOfTokens, Receiver[] receivers) Put a sequence of tokens to all receivers in the specified array.
void	putToAll(Token token, Receiver[] receivers) Put to all receivers in the specified array.
void	reset() Reset this receiver to its initial state, which in this base class is the same as calling clear().
void	setContainer(IOPort port) Set the container.
java.lang.String	toString() Return the class name and the full name of the object, with syntax "className {fullName}".

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractReceiver

public AbstractReceiver()

Construct an empty receiver with no container.

AbstractReceiver

public AbstractReceiver(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()
           throws IllegalActionException

Throw an exception. By default, a receiver that extends this class does not support this method.

Specified by:

clear in interface Receiver

Throws:

IllegalActionException - Always thrown.

elementList

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

Return a list with tokens that are currently in the receiver available for get() or getArray().

Specified by:

elementList in interface Receiver

Returns:

A list of instances of Token.

Throws:

IllegalActionException - Always thrown in this base class.

get

public abstract Token get()
                   throws NoTokenException

Get a token from this receiver.

Specified by:

get in interface Receiver

Returns:

A token read from the receiver.

Throws:

NoTokenException - If there is no token.

getArray

public Token[] getArray(int numberOfTokens)
                 throws NoTokenException

Get an array of tokens from this receiver. The numberOfTokens argument specifies the number of tokens to get. The length of the returned array will be equal to numberOfTokens.

This implementation works by calling get() repeatedly to populate an array. Derived classes may offer more efficient implementations. This implementation has two key limitations:

• The same array is reused on the next call to this method. Thus, the caller needs to ensure that it has accessed all the tokens it needs before the next call to this method occurs.
• The method is not synchronized.

These two limitations mean that this implementation is not suitable for multithreaded domains where there might be multiple threads reading from the same receiver. It is suitable, however, for multithreaded domains where only one thread is reading from the receiver. This is true even if a separate thread is writing to the receiver, as long as the put() and get() methods are properly synchronized.

Specified by:

getArray in interface Receiver

Parameters:

numberOfTokens - The number of tokens to get.

Returns:

The array of tokens.

Throws:

NoTokenException - If there are not numberOfTokens tokens available. Note that if this exception is thrown, then it is possible that some tokens will have been already extracted from the receiver by the calls to get(). These tokens will be lost. They will not be used on the next call to getArray(). Thus, it is highly advisable to call hasToken(int) before calling this method.

getContainer

public IOPort getContainer()

Return the container of this receiver, or null if there is none.

Specified by:

getContainer in interface Receiver

Returns:

The port containing this receiver.

See Also:

setContainer(IOPort)

getCurrentTime

@Deprecated
public double getCurrentTime()

Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()

Return the current time associated with this receiver. For non-DT receivers, this method reverts to the director's getCurrentTime() method. In DT, there is a local time associated with every receiver.

Returns:

The current time associated with this receiver.

getModelTime

public Time getModelTime()

Return the current time associated with this receiver. For non-DT receivers, this method reverts to the director's getCurrentTime() method. In DT, there is a local time associated with every receiver.

Returns:

The current time associated with this receiver.

hasRoom

public abstract boolean hasRoom()

Return true if the receiver has room to put a token into it (via the put() method). Returning true in this method guarantees that the next call to put() will not result in an exception.

Specified by:

hasRoom in interface Receiver

Returns:

True if the next call to put() will not result in a NoRoomException.

hasRoom

public abstract boolean hasRoom(int numberOfTokens)

Return true if the receiver has room to put the specified number of tokens into it (via the put() method). Returning true in this method guarantees that the next numberOfTokens calls to put() or a corresponding call to putArray() will not result in an exception.

Specified by:

hasRoom in interface Receiver

Parameters:

numberOfTokens - The number of tokens to put into this receiver.

Returns:

True if the next numberOfTokens calls to put() will not result in a NoRoomException.

hasToken

public abstract boolean hasToken()

Return true if the receiver contains a token that can be obtained by calling the get() method. In an implementation, returning true in this method guarantees that the next call to get() will not result in an exception.

Specified by:

hasToken in interface Receiver

Returns:

True if the next call to get() will not result in a NoTokenException.

hasToken

public abstract boolean hasToken(int numberOfTokens)

Return true if the receiver contains the specified number of tokens. In an implementation, returning true in this method guarantees that the next numberOfTokens calls to get(), or a corresponding call to getArray(), will not result in an exception.

Specified by:

hasToken in interface Receiver

Parameters:

numberOfTokens - The number of tokens desired.

Returns:

True if the next numberOfTokens calls to get() will not result in a NoTokenException.

isKnown

public boolean isKnown()

Return true. Most domains have no notion of the state of the receiver being unknown. It is always known whether there is a token available. Certain domains with fixed point semantics, however, such as SR, will need to override this method.

Specified by:

isKnown in interface Receiver

Returns:

True.

put

public abstract void put(Token token)
                  throws NoRoomException,
                         IllegalActionException

Put the specified token into this receiver. If the specified token is null, this can be interpreted by a receiver as an assertion that no token to be sent in the current round (for domains that have a notion of absent values and a current round).

Specified by:

put in interface Receiver

Parameters:

token - The token to put into the receiver, or null to put no token.

Throws:

NoRoomException - If there is no room in the receiver.

IllegalActionException - If the put fails (e.g. because of incompatible types).

putArray

public void putArray(Token[] tokenArray,
                     int numberOfTokens)
              throws NoRoomException,
                     IllegalActionException

Put a portion of the specified token array into this receiver. The first numberOfTokens elements of the token array are put into this receiver by repeated calling put(). The ability to specify a longer array than needed allows certain domains to have more efficient implementations.

This implementation works by calling put() repeatedly. The caller may feel free to reuse the array after this method returns. Derived classes may offer more efficient implementations. This implementation is not synchronized, so it is not suitable for multithreaded domains where there might be multiple threads writing to the same receiver. It is suitable, however, for multithreaded domains where only one thread is writing to the receiver. This is true even if a separate thread is reading from the receiver, as long as the put() and get() methods are properly synchronized.

Specified by:

putArray in interface Receiver

Parameters:

tokenArray - The array containing tokens to put into this receiver.

numberOfTokens - The number of elements of the token array to put into this receiver.

Throws:

NoRoomException - If the token array cannot be put.

IllegalActionException - If the token is not acceptable to one of the ports (e.g., wrong type).

putArrayToAll

public void putArrayToAll(Token[] tokens,
                          int numberOfTokens,
                          Receiver[] receivers)
                   throws NoRoomException,
                          IllegalActionException

Put a sequence of tokens to all receivers in the specified array. Implementers will assume that all such receivers are of the same class. This method simply calls putArray(Token[], int) on each receiver in the specified array, after appropriate type conversion. It also implements the functionality of ConstantPublisherPort in that it will replace the specified token with a constant value if the destination is marked to receive a constant value, and it will drop the token altogether if the destination has already received all the constant tokens it expects to receive. Note that subclasses that override this method will also have to implement this if they wish to support ConstantPublisherPort.

Specified by:

putArrayToAll in interface Receiver

Parameters:

tokens - The sequence of token to put.

numberOfTokens - The number of tokens to put (the array might be longer).

receivers - The receivers.

Throws:

NoRoomException - If there is no room for the token.

IllegalActionException - If the token is not acceptable to one of the ports (e.g., wrong type), or if the tokens array does not have at least the specified number of tokens.

putToAll

public void putToAll(Token token,
                     Receiver[] receivers)
              throws NoRoomException,
                     IllegalActionException

Put to all receivers in the specified array. This method simply calls put(Token) on each receiver in the specified array, after appropriate type conversion. It also implements the functionality of ConstantPublisherPort in that it will replace the specified token with a constant value if the destination is marked to receive a constant value, and it will drop the token altogether if the destination has already received all the constant tokens it expects to receive. Note that subclasses that override this method will also have to implement this if they wish to support ConstantPublisherPort.

Specified by:

putToAll in interface Receiver

Parameters:

token - The token to put, or null to put no token.

receivers - The receivers.

Throws:

NoRoomException - If there is no room for the token.

IllegalActionException - If the token is not acceptable to one of the ports (e.g., wrong type).

reset

public void reset()
           throws IllegalActionException

Reset this receiver to its initial state, which in this base class is the same as calling clear().

Specified by:

reset in interface Receiver

Throws:

IllegalActionException - If reset() is not supported by the domain.

setContainer

public void setContainer(IOPort port)
                  throws IllegalActionException

Set the container.

Specified by:

setContainer in interface Receiver

Parameters:

port - The container.

Throws:

IllegalActionException - If the container is not of an appropriate subclass of IOPort. Not thrown in this base class, but may be thrown in derived classes.

See Also:

getContainer()

toString

public java.lang.String toString()

Return the class name and the full name of the object, with syntax "className {fullName}".

Overrides:

toString in class java.lang.Object

Returns:

The class name and the full name.