Package ptolemy.actor

Class AbstractReceiver

    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractReceiver()
      Construct an empty receiver with no container.
      AbstractReceiver​(IOPort container)
      Construct an empty receiver with the specified container.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void clear()
      Throw an exception.
      java.util.List<Token> elementList()
      Return a list with tokens that are currently in the receiver available for get() or getArray().
      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()
      Deprecated.
      As of Ptolemy II 4.1, replaced by getModelTime()
      Time getModelTime()
      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.
      abstract 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 to all receivers in the specified array.
      void reset()
      Reset this receiver to its initial state, which in this base class is the same as calling clear().
      void setContainer​(IOPort port)
      Set the container.
      java.lang.String toString()
      Return the class name and the full name of the object, with syntax "className {fullName}".
      • Methods inherited from class java.lang.Object

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

      • elementList

        public java.util.List<Token> elementList()
                                          throws IllegalActionException
        Return a list with tokens that are currently in the receiver available for get() or getArray().
        Specified by:
        elementList in interface Receiver
        Returns:
        A list of instances of Token.
        Throws:
        IllegalActionException - Always thrown in this base class.
      • 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 will be equal to numberOfTokens.

        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.
        Returns:
        The array of tokens.
        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.
        See Also:
        setContainer(IOPort)
      • getCurrentTime

        @Deprecated
        public double getCurrentTime()
        Deprecated.
        As of Ptolemy II 4.1, replaced by getModelTime()
        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.
      • getModelTime

        public Time getModelTime()
        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. Most domains have no notion of the state of the receiver being unknown. It is always known whether there is a token available. Certain domains with fixed point semantics, however, such as SR, will need to override this method.
        Specified by:
        isKnown in interface Receiver
        Returns:
        True.
      • put

        public abstract 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).
        Specified by:
        put in interface Receiver
        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 put fails (e.g. because of incompatible types).
      • putArray

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

        public 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. This method simply calls putArray(Token[], int) on each receiver in the specified array, after appropriate type conversion. It also implements the functionality of ConstantPublisherPort in that it will replace the specified token with a constant value if the destination is marked to receive a constant value, and it will drop the token altogether if the destination has already received all the constant tokens it expects to receive. Note that subclasses that override this method will also have to implement this if they wish to support ConstantPublisherPort.
        Specified by:
        putArrayToAll in interface Receiver
        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), or if the tokens array does not have at least the specified number of tokens.
      • putToAll

        public void putToAll​(Token token,
                             Receiver[] receivers)
                      throws NoRoomException,
                             IllegalActionException
        Put to all receivers in the specified array. This method simply calls put(Token) on each receiver in the specified array, after appropriate type conversion. It also implements the functionality of ConstantPublisherPort in that it will replace the specified token with a constant value if the destination is marked to receive a constant value, and it will drop the token altogether if the destination has already received all the constant tokens it expects to receive. Note that subclasses that override this method will also have to implement this if they wish to support ConstantPublisherPort.
        Specified by:
        putToAll in interface Receiver
        Parameters:
        token - The token to put, or null to put 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).
      • toString

        public java.lang.String toString()
        Return the class name and the full name of the object, with syntax "className {fullName}".
        Overrides:
        toString in class java.lang.Object
        Returns:
        The class name and the full name.