ptolemy.actor
Interface Receiver

All Known Subinterfaces:
ProcessReceiver
All Known Implementing Classes:
AbstractReceiver, CSPReceiver, DDEReceiver, MailboxBoundaryReceiver, PNQueueReceiver

public interface Receiver

Interface for objects that can hold tokens. An implementation of this interface has two key methods: put() and get(). The put() method deposits a token into the receiver. The get() method retrieves a token that has been put. The order of the retrieved tokens depends on specific implementations, and does not necessarily match the order in which tokens have been put.

All implementations of this interface must follow these rules, regardless of the number of threads that are accessing the receiver:

In general, this means that multithreaded domains must provide synchronization for receivers. Note that both NoTokenException and NoRoomException are runtime exceptions, so they need not be declared explicitly.

Objects that implement this interface can only be contained by an instance of IOPort.

Since:
Ptolemy II 0.2
Version:
$Id: Receiver.java,v 1.54 2004/04/13 02:58:03 cxh Exp $
Author:
Jie Liu, Edward A. Lee, Lukito Muliadi
See Also:
Token
Accepted Rating:
Green (bart)
Proposed Rating:
Green (eal)

Method Summary
 void clear()
          Clear this receiver of any contained tokens.
 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.
 boolean hasRoom()
          Return true if the receiver has room to put a token into it (via the put() method).
 boolean hasRoom(int numberOfTokens)
          Return true if the receiver has room to put the specified number of tokens into it (via the put() method).
 boolean hasToken()
          Return true if the receiver contains a token that can be obtained by calling the get() method.
 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 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 setContainer(IOPort port)
          Set the container.
 

Method Detail

clear

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

Throws:
IllegalActionException - If clear() is not supported by the domain.

get

public Token get()
          throws NoTokenException
Get a token from this 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. In an implementation, the length of the returned array is allowed to be greater than numberOfTokens, in which case, only the first numberOfTokens elements are the ones that have been read from the receiver. In some domains, this allows the implementation to be more efficient.

Parameters:
numberOfTokens - The number of tokens to get in the returned array.
Returns:
An array of tokens read from the receiver.
Throws:
NoTokenException - If there are not numberOfTokens tokens.

getContainer

public IOPort getContainer()
Return the container of this receiver, or null if there is none.

Returns:
The port containing this receiver.

hasRoom

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

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

hasRoom

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

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

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

hasToken

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

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 this receiver is known not to contain any tokens. This method supports domains, such as SR, which have fixed-point semantics. In such domains, an iteration of a model starts with the state of all channels unknown, and the iteration concludes when the state of all channels is known. In domains that have no such notion, this method should simply return true.

Returns:
True if this receiver has known state.

put

public void put(Token token)
         throws NoRoomException
Put the specified token into this 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. The ability to specify a longer array than needed allows certain domains to have more efficient implementations.

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.

setContainer

public void setContainer(IOPort port)
                  throws IllegalActionException
Set the container.

Parameters:
port - The container.
Throws:
IllegalActionException - If the container is not of an appropriate subclass of IOPort for the particular receiver implementation.