Package ptolemy.actor

Class QueueReceiver

  • All Implemented Interfaces:
    Receiver
    Direct Known Subclasses:
    PNQueueReceiver
    public class QueueReceiver
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 oldest one in the receiver. 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:
    Edward A. Lee, Lukito Muliadi, Xiaojun Liu
    See Also:
    FIFOQueue
    Pt.AcceptedRating:
    Green (liuj)
    Pt.ProposedRating:
    Green (eal)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected FIFOQueue _queue
      This is the queue in which data is stored.
      static int INFINITE_CAPACITY
      Used to indicate that the size of this queue receiver is infinite.

    • Constructor Summary

      Constructors 
      Constructor Description
      QueueReceiver()
      Construct an empty receiver with no container.
      QueueReceiver​(IOPort container)
      Construct an empty receiver with the specified container.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void clear()
      Clear this receiver of any contained tokens.
      java.util.List<Token> elementList()
      List the tokens in the receiver, beginning with the oldest.
      java.util.Enumeration elements()
      Deprecated.
      Used elementList() instead.
      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.
      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 the next call to put() will succeed without a NoRoomException.
      boolean hasRoom​(int numberOfTokens)
      Return true if the queue has room to put the given number of tokens into it (via the put() method).
      boolean hasToken()
      Return true if the next call to get() will succeed without a a NoTokenException.
      boolean hasToken​(int numberOfTokens)
      Return true if the specified number of tokens is available in the queue.
      java.util.List historyElementList()
      Deprecated.
      Used historyElementList() instead.
      java.util.Enumeration historyElements()
      Deprecated.
      Used historyElementList() instead.
      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
        Used to indicate that the size of this queue receiver is infinite.
        See Also:
        Constant Field Values

      • _queue

        protected FIFOQueue _queue
        This is the queue in which data is stored.

    • Constructor Detail

      • QueueReceiver

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

      • QueueReceiver

        public QueueReceiver​(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

      • elements

        @Deprecated
public java.util.Enumeration elements()
        Deprecated.
        Used elementList() instead.
        Enumerate the tokens in the receiver, beginning with the oldest.
        Returns:
        An enumeration of tokens.

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

      • 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:
        setHistoryCapacity(int)

      • hasRoom

        public boolean hasRoom()
        Return true if the next call to put() will succeed without a NoRoomException.
        Specified by:
        hasRoom in interface Receiver
        Specified by:
        hasRoom in class AbstractReceiver
        Returns:
        True if the queue has room for one more token.

      • hasRoom

        public boolean hasRoom​(int numberOfTokens)
                throws java.lang.IllegalArgumentException
        Return true if the queue has room to put the given number of tokens into it (via the put() method).
        Specified by:
        hasRoom in interface Receiver
        Specified by:
        hasRoom in class AbstractReceiver
        Parameters:
        numberOfTokens - The number of tokens to put into the queue.
        Returns:
        True if the queue has room for the specified number of tokens.
        Throws:
        java.lang.IllegalArgumentException - If the number of tokens is less than one. This is a runtime exception, and hence does not need to be explicitly declared by the caller.

      • hasToken

        public boolean hasToken()
        Return true if the next call to get() will succeed without a a NoTokenException.
        Specified by:
        hasToken in interface Receiver
        Specified by:
        hasToken in class AbstractReceiver
        Returns:
        True if the queue has at least one token in it.

      • hasToken

        public boolean hasToken​(int numberOfTokens)
                 throws java.lang.IllegalArgumentException
        Return true if the specified number of tokens is available in the queue.
        Specified by:
        hasToken in interface Receiver
        Specified by:
        hasToken in class AbstractReceiver
        Parameters:
        numberOfTokens - The number of tokens to get from the queue.
        Returns:
        True if the specified number of tokens is available.
        Throws:
        java.lang.IllegalArgumentException - If the number of tokens is less than one. This is a runtime exception, and hence does not need to be explicitly declared by the caller.

      • historyElementList

        @Deprecated
public java.util.List historyElementList()
        Deprecated.
        Used historyElementList() instead.
        List 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.

      • historyElements

        @Deprecated
public java.util.Enumeration historyElements()
        Deprecated.
        Used historyElementList() instead.
        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.

      • historySize

        public int historySize()
        Return the number of tokens in history.
        Returns:
        The number of tokens in history.

      • put

        public void put​(Token token)
        Put a token to the receiver. If the receiver is full, throw an exception. If the argument is null, do nothing.
        Specified by:
        put in interface Receiver
        Specified by:
        put in class AbstractReceiver
        Parameters:
        token - The token to be put to the receiver.
        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()

      • size

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