ptolemy.actor
Class AbstractReceiver

java.lang.Object
  |
  +--ptolemy.actor.AbstractReceiver

All Implemented Interfaces:

Receiver

Direct Known Subclasses:

CSPReceiver, DEReceiver, GiottoReceiver, Mailbox, PrioritizedTimedQueue, QueueReceiver, SDFReceiver, 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: AbstractReceiver.java,v 1.23 2002/02/21 18:52:26 cxh Exp $

Author:

Steve Neuendorffer

See Also:

Receiver

Constructor Summary

AbstractReceiver()
Construct an empty receiver with no container.

AbstractReceiver(IOPort container)
Construct an empty receiver with the specified container.

Method Summary

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() 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 if this receiver has known state, that is, the tokens in this receiver are known or if this receiver is known not to contain any tokens.
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	setAbsent() Set the receiver to contain no tokens.
void	setContainer(IOPort port) Set the container.

Methods inherited from class java.lang.Object

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

get

public abstract Token get()
                   throws NoTokenException

Get a token from this receiver.

Specified by:

get in interface 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 may be greater than numberOfTokens, in which case, the first numberOfTokens elements are the newly obtained tokens.

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.

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.

getCurrentTime

public double getCurrentTime()

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 if this receiver has known state, that is, the tokens in this receiver are known or if this receiver is known not to contain any tokens.

In this base class, assume that the receiver has known state, so return true. Receivers that may have unknown state must override this method.

Specified by:

isKnown in interface Receiver

Returns:

True.

put

public void put(Token token)
         throws NoRoomException

Put the specified token into this receiver.

Specified by:

put in interface Receiver

Parameters:

token - The token to put into the receiver.

Throws:

NoRoomException - If there is no room in the receiver.

putArray

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

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.

setAbsent

public void setAbsent()

Set the receiver to contain no tokens.

In this base class, do nothing. Receivers that require some action to be performed must override this method.

Specified by:

setAbsent in interface Receiver

Throws:

NoRoomException - If there is no room in the receiver.

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.