001/* Interface for objects that can store tokens.
002
003 Copyright (c) 1997-2013 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027
028 */
029package ptolemy.actor;
030
031import java.util.List;
032
033import ptolemy.data.Token;
034import ptolemy.kernel.util.IllegalActionException;
035
036///////////////////////////////////////////////////////////////////
037//// Receiver
038
039/**
040 Interface for objects that can hold tokens. An implementation of this
041 interface has two key methods: put() and get(). The put() method
042 deposits a token into the receiver. The get() method retrieves
043 a token that has been put. The order of
044 the retrieved tokens depends on specific implementations, and does not
045 necessarily match the order in which tokens have been put.
046 <p>
047 All implementations of this interface must follow these rules, regardless
048 of the number of threads that are accessing the receiver:
049 <ul>
050 <li> If hasToken() returns true, then the next call to get() must not
051 result in a NoTokenException being thrown.
052 <li> If hasRoom() returns true, then the next call to put() must not
053 result in a NoRoomException being thrown.
054 </ul>
055 In general, this means that multithreaded domains must provide
056 synchronization for receivers. Note that both NoTokenException
057 and NoRoomException are runtime exceptions, so they need not be
058 declared explicitly.
059 <p>
060 Objects that implement this interface can only be contained
061 by an instance of IOPort.
062
063 @author Jie Liu, Edward A. Lee, Lukito Muliadi
064 @version $Id$
065 @since Ptolemy II 0.2
066 @Pt.ProposedRating Green (eal)
067 @Pt.AcceptedRating Green (bart)
068 @see Token
069 */
070public interface Receiver {
071    ///////////////////////////////////////////////////////////////////
072    ////                         public methods                    ////
073
074    /** Clear this receiver of any contained tokens.
075     *  @exception IllegalActionException If clear() is not supported by
076     *   the domain.
077     */
078    public void clear() throws IllegalActionException;
079
080    /** Return a list with tokens that are currently in the receiver
081     *  available for get() or getArray(). The oldest token (the one
082     *  that was put first) should be listed first in any implementation
083     *  of this method.
084     *  @return A list of instances of Token.
085     *  @exception IllegalActionException If the operation is not supported.
086     */
087    public List<Token> elementList() throws IllegalActionException;
088
089    /** Get a token from this receiver.
090     *  @return A token read from the receiver.
091     *  @exception NoTokenException If there is no token.
092     */
093    public Token get() throws NoTokenException;
094
095    /** Get an array of tokens from this receiver. The <i>numberOfTokens</i>
096     *  argument specifies the number of tokens to get. In an implementation,
097     *  the length of the returned array must be equal to
098     *  <i>numberOfTokens</i>.
099     *  @param numberOfTokens The number of tokens to get in the
100     *   returned array.
101     *  @return An array of tokens read from the receiver.
102     *  @exception NoTokenException If there are not <i>numberOfTokens</i>
103     *   tokens.
104     */
105    public Token[] getArray(int numberOfTokens) throws NoTokenException;
106
107    /** Return the container of this receiver, or null if there is none.
108     *  @return The port containing this receiver.
109     *  @see #setContainer(IOPort)
110     */
111    public IOPort getContainer();
112
113    /** Return true if the receiver has room to put a token into it
114     *  (via the put() method).
115     *  Returning true in this method guarantees that the next call to
116     *  put() will not result in an exception.
117     *  @return True if the next call to put() will not result in a
118     *   NoRoomException.
119     */
120    public boolean hasRoom();
121
122    /** Return true if the receiver has room to put the specified number of
123     *  tokens into it (via the put() method).
124     *  Returning true in this method guarantees that the next
125     *  <i>numberOfTokens</i> calls to put() or a corresponding call
126     *  to putArray() will not result in an exception.
127     *  @param numberOfTokens The number of tokens to put into this receiver.
128     *  @return True if the next <i>numberOfTokens</i> calls to put()
129     *   will not result in a NoRoomException.
130     */
131    public boolean hasRoom(int numberOfTokens);
132
133    /** Return true if the receiver contains a token that can be obtained
134     *  by calling the get() method.  In an implementation,
135     *  returning true in this method guarantees that the next
136     *  call to get() will not result in an exception.
137     *  @return True if the next call to get() will not result in a
138     *   NoTokenException.
139     */
140    public boolean hasToken();
141
142    /** Return true if the receiver contains the specified number of tokens.
143     *  In an implementation, returning true in this method guarantees
144     *  that the next <i>numberOfTokens</i> calls to get(), or a
145     *  corresponding call to getArray(), will not result in an exception.
146     *  @param numberOfTokens The number of tokens desired.
147     *  @return True if the next <i>numberOfTokens</i> calls to get()
148     *   will not result in a NoTokenException.
149     */
150    public boolean hasToken(int numberOfTokens);
151
152    /** Return <i>true</i> if this receiver has known state;
153     *  that is, the tokens in this receiver are known, or this
154     *  receiver is known not to contain any tokens.
155     *  This method supports domains, such as SR, which have fixed-point
156     *  semantics.  In such domains, an iteration of a model starts with
157     *  the state of all channels unknown, and the iteration concludes when
158     *  the state of all channels is known. In domains that have no such
159     *  notion, this method should simply return <i>true</i>.
160     *  @return True if this receiver has known state.
161     */
162    public boolean isKnown();
163
164    /** Put the specified token into this receiver.
165     *  If the specified token is null, this can be interpreted by
166     *  a receiver as an assertion that no token to be sent in the
167     *  current round (for domains that have a notion of absent values
168     *  and a current round).
169     *  @param token The token to put into the receiver, or null to
170     *   put no token.
171     *  @exception NoRoomException If there is no room in the receiver.
172     *  @exception IllegalActionException If the token is not acceptable
173     *   to one of the ports (e.g., wrong type).
174     */
175    public void put(Token token) throws NoRoomException, IllegalActionException;
176
177    /** Put a portion of the specified token array into this receiver.
178     *  The first <i>numberOfTokens</i> elements of the token array are put
179     *  into this receiver.  The ability to specify a longer array than
180     *  needed allows certain domains to have more efficient implementations.
181     *  @param tokenArray The array containing tokens to put into this
182     *   receiver.
183     *  @param numberOfTokens The number of elements of the token
184     *   array to put into this receiver.
185     *  @exception NoRoomException If the token array cannot be put.
186     *  @exception IllegalActionException If the token is not acceptable
187     *   to one of the ports (e.g., wrong type).
188     */
189    public void putArray(Token[] tokenArray, int numberOfTokens)
190            throws NoRoomException, IllegalActionException;
191
192    /** Put a sequence of tokens to all receivers in the specified array.
193     *  Implementers will assume that all such receivers
194     *  are of the same class.
195     *  @param tokens The sequence of token to put.
196     *  @param numberOfTokens The number of tokens to put (the array might
197     *   be longer).
198     *  @param receivers The receivers.
199     *  @exception NoRoomException If there is no room for the token.
200     *  @exception IllegalActionException If the token is not acceptable
201     *   to one of the ports (e.g., wrong type).
202     */
203    public void putArrayToAll(Token[] tokens, int numberOfTokens,
204            Receiver[] receivers)
205            throws NoRoomException, IllegalActionException;
206
207    /** Put a single token to all receivers in the specified array.
208     *  If the specified token is null, this can be interpreted by
209     *  a receiver as an assertion that no token to be sent in the
210     *  current round (for domains that have a notion of absent values
211     *  and a current round).
212     *  Implementers will assume that all such receivers
213     *  are of the same class.
214     *  @param token The token to put, or null to send no token.
215     *  @param receivers The receivers.
216     *  @exception NoRoomException If there is no room for the token.
217     *  @exception IllegalActionException If the token is not acceptable
218     *   to one of the ports (e.g., wrong type).
219     */
220    public void putToAll(Token token, Receiver[] receivers)
221            throws NoRoomException, IllegalActionException;
222
223    /** Reset this receiver to its initial state, which is typically
224     *  either empty (same as calling clear()) or unknown.
225     *  @exception IllegalActionException If reset() is not supported by
226     *   the domain.
227     */
228    public void reset() throws IllegalActionException;
229
230    /** Set the container.
231     *  @param port The container.
232     *  @exception IllegalActionException If the container is not of
233     *   an appropriate subclass of IOPort for the particular receiver
234     *   implementation.
235     *  @see #getContainer()
236     */
237    public void setContainer(IOPort port) throws IllegalActionException;
238}