/* Interface for objects that can store tokens. Copyright (c) 1997-2013 The Regents of the University of California. All rights reserved. Permission is hereby granted, without written agreement and without license or royalty fees, to use, copy, modify, and distribute this software and its documentation for any purpose, provided that the above copyright notice and the following two paragraphs appear in all copies of this software. IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. PT_COPYRIGHT_VERSION_2 COPYRIGHTENDKEY */ package ptolemy.actor; import java.util.List; import ptolemy.data.Token; import ptolemy.kernel.util.IllegalActionException; /////////////////////////////////////////////////////////////////// //// 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. @author Jie Liu, Edward A. Lee, Lukito Muliadi @version $Id: Receiver.java 65763 2013-03-07 01:54:37Z cxh $ @since Ptolemy II 0.2 @Pt.ProposedRating Green (eal) @Pt.AcceptedRating Green (bart) @see Token */ public interface Receiver { /////////////////////////////////////////////////////////////////// //// public methods //// /** Clear this receiver of any contained tokens. * @exception IllegalActionException If clear() is not supported by * the domain. */ public void clear() 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. * @return A list of instances of Token. * @exception IllegalActionException If the operation is not supported. */ public List elementList() throws IllegalActionException; /** Get a token from this receiver. * @return A token read from the receiver. * @exception NoTokenException If there is no token. */ public Token get() 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. * @param numberOfTokens The number of tokens to get in the * returned array. * @return An array of tokens read from the receiver. * @exception NoTokenException If there are not numberOfTokens * tokens. */ public Token[] getArray(int numberOfTokens) throws NoTokenException; /** Return the container of this receiver, or null if there is none. * @return The port containing this receiver. * @see #setContainer(IOPort) */ public IOPort getContainer(); /** 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. * @return True if the next call to put() will not result in a * NoRoomException. */ public boolean hasRoom(); /** 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. * @param numberOfTokens The number of tokens to put into this receiver. * @return True if the next numberOfTokens calls to put() * will not result in a NoRoomException. */ public boolean hasRoom(int numberOfTokens); /** 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. * @return True if the next call to get() will not result in a * NoTokenException. */ public boolean hasToken(); /** 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. * @param numberOfTokens The number of tokens desired. * @return True if the next numberOfTokens calls to get() * will not result in a NoTokenException. */ public boolean hasToken(int numberOfTokens); /** 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. * @return True if this receiver has known state. */ public boolean isKnown(); /** 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). * @param token The token to put into the receiver, or null to * put no token. * @exception NoRoomException If there is no room in the receiver. * @exception IllegalActionException If the token is not acceptable * to one of the ports (e.g., wrong type). */ public void put(Token token) 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. * @param tokenArray The array containing tokens to put into this * receiver. * @param numberOfTokens The number of elements of the token * array to put into this receiver. * @exception NoRoomException If the token array cannot be put. * @exception IllegalActionException If the token is not acceptable * to one of the ports (e.g., wrong type). */ public void putArray(Token[] tokenArray, int numberOfTokens) 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. * @param tokens The sequence of token to put. * @param numberOfTokens The number of tokens to put (the array might * be longer). * @param receivers The receivers. * @exception NoRoomException If there is no room for the token. * @exception IllegalActionException If the token is not acceptable * to one of the ports (e.g., wrong type). */ public void putArrayToAll(Token[] tokens, int numberOfTokens, 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. * @param token The token to put, or null to send no token. * @param receivers The receivers. * @exception NoRoomException If there is no room for the token. * @exception IllegalActionException If the token is not acceptable * to one of the ports (e.g., wrong type). */ public void putToAll(Token token, Receiver[] receivers) throws NoRoomException, IllegalActionException; /** Reset this receiver to its initial state, which is typically * either empty (same as calling clear()) or unknown. * @exception IllegalActionException If reset() is not supported by * the domain. */ public void reset() throws IllegalActionException; /** Set the container. * @param port The container. * @exception IllegalActionException If the container is not of * an appropriate subclass of IOPort for the particular receiver * implementation. * @see #getContainer() */ public void setContainer(IOPort port) throws IllegalActionException; }