Package ptolemy.domains.sdf.kernel

Class SDFReceiver

  • All Implemented Interfaces:
    Receiver
    Direct Known Subclasses:
    DistributedSDFReceiver, DTReceiver, PthalesReceiver
    public class SDFReceiver
extends AbstractReceiver
    A first-in, first-out (FIFO) queue receiver with variable capacity and optional history. Tokens are put into the receiver with the put() method, and removed from the receiver with the get() method. The token removed is the one placed in the receiver before any other (i.e. the "oldest", although this has nothing to do with time in the model. By default, the capacity is unbounded, but it can be set to any nonnegative size. If the history capacity is greater than zero (or infinite, indicated by a capacity of INFINITE_CAPACITY), then tokens removed from the receiver are stored in a history queue rather than simply removed. By default, the history capacity is zero.
    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Steve Neuendorffer
    See Also:
    ArrayFIFOQueue
    Pt.AcceptedRating:
    Green (neuendor)
    Pt.ProposedRating:
    Green (neuendor)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      int _waitingTokens
      The number of tokens waiting to be consumed during scheduling.
      static int INFINITE_CAPACITY
      A constant indicating that the capacity of the receiver is unbounded.

    • Constructor Summary

      Constructors 
      Constructor Description
      SDFReceiver()
      Construct an empty receiver with no container.
      SDFReceiver​(int size)
      Construct an empty receiver with no container and given size.
      SDFReceiver​(IOPort container)
      Construct an empty receiver with the specified container.
      SDFReceiver​(IOPort container, int size)
      Construct an empty receiver with the specified container and size.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()
      Clear this receiver of any contained tokens.
      java.util.List<Token> elementList()
      Return a list with the tokens currently in the receiver, or an empty list if there are no such tokens.
      Token get()
      Remove the first token (the oldest one) from the receiver and return it.
      Token get​(int offset)
      Return a token in the receiver or its history.
      Token[] getArray​(int count)
      Get an array of tokens from this receiver.
      int getCapacity()
      Return the capacity, or INFINITE_CAPACITY if it is unbounded.
      int getHistoryCapacity()
      Return the capacity of the history queue.
      boolean hasRoom()
      Return true if put() will succeed in accepting a token.
      boolean hasRoom​(int tokens)
      Return true if put() will succeed in accepting the specified number of tokens.
      boolean hasToken()
      Return true if get() will succeed in returning a token.
      boolean hasToken​(int tokens)
      Return true if get() will succeed in returning a token the given number of times.
      java.util.Enumeration historyElements()
      Enumerate the tokens stored in the history queue, which are the N most recent tokens taken from the receiver, beginning with the oldest, where N is less than or equal to the history capacity.
      int historySize()
      Return the number of tokens in history.
      void put​(Token token)
      Put a token to the receiver.
      void setCapacity​(int capacity)
      Set receiver capacity.
      void setHistoryCapacity​(int capacity)
      Set the capacity of the history queue.
      int size()
      Return the number of tokens in the receiver.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • INFINITE_CAPACITY

        public static final int INFINITE_CAPACITY
        A constant indicating that the capacity of the receiver is unbounded.
        See Also:
        Constant Field Values

      • _waitingTokens

        public int _waitingTokens
        The number of tokens waiting to be consumed during scheduling.

    • Constructor Detail

      • SDFReceiver

        public SDFReceiver()
        Construct an empty receiver with no container.

      • SDFReceiver

        public SDFReceiver​(int size)
        Construct an empty receiver with no container and given size.
        Parameters:
        size - The size of the queue in the receiver.

      • SDFReceiver

        public SDFReceiver​(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.

      • SDFReceiver

        public SDFReceiver​(IOPort container,
                   int size)
            throws IllegalActionException
        Construct an empty receiver with the specified container and size.
        Parameters:
        container - The container of the receiver.
        size - The size of the queue in the receiver.
        Throws:
        IllegalActionException - If the container does not accept this receiver.

    • Method Detail

      • elementList

        public java.util.List<Token> elementList()
        Return a list with the tokens currently in the receiver, or an empty list if there are no such tokens.
        Specified by:
        elementList in interface Receiver
        Overrides:
        elementList in class AbstractReceiver
        Returns:
        A list of instances of Token.

      • get

        public Token get()
        Remove the first token (the oldest one) from the receiver and return it. If there is no token in the receiver, throw an exception.
        Specified by:
        get in interface Receiver
        Specified by:
        get in class AbstractReceiver
        Returns:
        The oldest token in the receiver.
        Throws:
        NoTokenException - If there is no token in the receiver.

      • get

        public Token get​(int offset)
        Return a token in the receiver or its history. If the offset argument is zero, return the oldest token in the receiver. If the offset is 1, return the second oldest token, etc. The token is not removed from the receiver. If there is no such token in the receiver (the offset is greater than or equal to the number of tokens currently in the receiver), throw an exception. If the offset is -1, return the most recent token removed from the receiver. If it is -2, return the second most recent token removed from the receiver, etc. If there is no such token in the receiver's history (the history capacity is zero or the absolute value of offset is greater than the number of tokens currently in the receiver's history), an exception is thrown.
        Parameters:
        offset - The offset from the oldest token in the receiver.
        Returns:
        The token at the desired offset in the receiver or its history.
        Throws:
        NoTokenException - If the offset is out of range.

      • getArray

        public Token[] getArray​(int count)
        Get an array of tokens from this receiver. The parameter specifies the number of valid tokens to get in the returned array. The length of the returned array will be equal to count.
        Specified by:
        getArray in interface Receiver
        Overrides:
        getArray in class AbstractReceiver
        Parameters:
        count - The number of valid tokens to get in the returned array.
        Returns:
        An array containing count tokens from the receiver.
        Throws:
        NoTokenException - If there are not count tokens.

      • getCapacity

        public int getCapacity()
        Return the capacity, or INFINITE_CAPACITY if it is unbounded.
        Returns:
        The capacity of the receiver.
        See Also:
        setCapacity(int)

      • getHistoryCapacity

        public int getHistoryCapacity()
        Return the capacity of the history queue. This will be zero if the history mechanism is disabled and INFINITE_CAPACITY if the history capacity is unbounded.
        Returns:
        The capacity of the history queue.
        See Also:
        historyElements(), historySize(), setHistoryCapacity(int)

      • hasRoom

        public boolean hasRoom()
        Return true if put() will succeed in accepting a token.
        Specified by:
        hasRoom in interface Receiver
        Specified by:
        hasRoom in class AbstractReceiver
        Returns:
        A boolean indicating whether a token can be put in this receiver.

      • hasRoom

        public boolean hasRoom​(int tokens)
                throws java.lang.IllegalArgumentException
        Return true if put() will succeed in accepting the specified number of tokens.
        Specified by:
        hasRoom in interface Receiver
        Specified by:
        hasRoom in class AbstractReceiver
        Parameters:
        tokens - The number of tokens.
        Returns:
        A boolean indicating whether a token can be put in this receiver.
        Throws:
        java.lang.IllegalArgumentException - If the argument is less than one. This is a runtime exception, so it need not be declared explicitly by the caller.

      • hasToken

        public boolean hasToken()
        Return true if get() will succeed in returning a token.
        Specified by:
        hasToken in interface Receiver
        Specified by:
        hasToken in class AbstractReceiver
        Returns:
        A boolean indicating whether there is a token in this receiver.

      • hasToken

        public boolean hasToken​(int tokens)
                 throws java.lang.IllegalArgumentException
        Return true if get() will succeed in returning a token the given number of times.
        Specified by:
        hasToken in interface Receiver
        Specified by:
        hasToken in class AbstractReceiver
        Parameters:
        tokens - The number of tokens.
        Returns:
        A boolean indicating whether there are the given number of tokens in this receiver.
        Throws:
        java.lang.IllegalArgumentException - If the argument is less than one. This is a runtime exception, so it need not be declared explicitly by the caller.

      • historyElements

        public java.util.Enumeration historyElements()
        Enumerate the tokens stored in the history queue, which are the N most recent tokens taken from the receiver, beginning with the oldest, where N is less than or equal to the history capacity. If the history capacity is INFINITE_CAPACITY, then the enumeration includes all tokens previously taken from the receiver. If the history capacity is zero, then return an empty enumeration.
        Returns:
        An enumeration of tokens.
        See Also:
        getHistoryCapacity(), historySize(), setHistoryCapacity(int)

      • put

        public void put​(Token token)
        Put a token to the receiver. If the receiver is full, throw an exception.
        Specified by:
        put in interface Receiver
        Specified by:
        put in class AbstractReceiver
        Parameters:
        token - The token to be put to the receiver, or null to not put any token.
        Throws:
        NoRoomException - If the receiver is full.

      • setCapacity

        public void setCapacity​(int capacity)
                 throws IllegalActionException
        Set receiver capacity. Use INFINITE_CAPACITY to indicate unbounded capacity (which is the default). If the number of tokens currently in the receiver exceeds the desired capacity, throw an exception.
        Parameters:
        capacity - The desired receiver capacity.
        Throws:
        IllegalActionException - If the receiver has more tokens than the proposed capacity or the proposed capacity is illegal.
        See Also:
        getCapacity()

      • setHistoryCapacity

        public void setHistoryCapacity​(int capacity)
                        throws IllegalActionException
        Set the capacity of the history queue. Use 0 to disable the history mechanism and INFINITE_CAPACITY to make the history capacity unbounded. If the size of the history queue exceeds the desired capacity, then remove the oldest tokens from the history queue until its size equals the proposed capacity. Note that this can be used to clear the history queue by supplying 0 as the argument.
        Parameters:
        capacity - The desired history capacity.
        Throws:
        IllegalActionException - If the desired capacity is illegal.
        See Also:
        getHistoryCapacity(), historyElements(), historySize()

      • size

        public int size()
        Return the number of tokens in the receiver.
        Returns:
        The number of tokens in the receiver.