ptolemy.actor
Interface Receiver

All Known Subinterfaces:

ProcessReceiver

All Known Implementing Classes:

AbstractReceiver, CIReceiver, CSPReceiver, CTReceiver, DDEReceiver, DEReceiver, DistributedReceiver, DistributedSDFReceiver, DTReceiver, FixedPointReceiver, FSMReceiver, GiottoReceiver, GRReceiver, Mailbox, MailboxBoundaryReceiver, PNQueueReceiver, PrioritizedTimedQueue, QueueReceiver, RendezvousReceiver, SDFReceiver, TDLReceiver, TMReceiver, WirelessReceiver

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:

• If hasToken() returns true, then the next call to get() must not result in a NoTokenException being thrown.
• If hasRoom() returns true, then the next call to put() must not result in a NoRoomException being thrown.

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 57040 2010-01-27 20:52:32Z cxh $

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.
java.util.List<Token>	elementList() Return a list with tokens that are currently in the receiver available for get() or getArray().
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	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 a single token to all receivers in the specified array.
void	reset() Reset this receiver to its initial state, which is typically either empty (same as calling clear()) or unknown.
void	setContainer(IOPort port) Set the container.

Method Detail

clear

void clear()
           throws IllegalActionException

Clear this receiver of any contained tokens.

Throws:

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

elementList

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

Return a list with tokens that are currently in the receiver available for get() or getArray(). The oldest token (the one that was put first) should be listed first in any implementation of this method.

Returns:

A list of instances of Token.

Throws:

IllegalActionException - If the operation is not supported.

get

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

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 must be equal to numberOfTokens.

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

IOPort getContainer()

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

Returns:

The port containing this receiver.

See Also:

setContainer(IOPort)

hasRoom

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

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

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

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

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

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

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 token is not acceptable to one of the ports (e.g., wrong type).

putArray

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

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

putArrayToAll

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.

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

putToAll

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

Put a single token to all receivers in the specified array. 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). Implementers will assume that all such receivers are of the same class.

Parameters:

token - The token to put, or null to send 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

void reset()
           throws IllegalActionException

Reset this receiver to its initial state, which is typically either empty (same as calling clear()) or unknown.

Throws:

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

setContainer

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.

See Also:

getContainer()