Class DDEReceiver

  • All Implemented Interfaces:
    ProcessReceiver, Receiver

    public class DDEReceiver
    extends PrioritizedTimedQueue
    implements ProcessReceiver
    A DDEReceiver stores time stamped tokens according to distributed discrete event semantics. A time stamped token is a token that has a time stamp associated with it. A DDEReceiver stores time stamped tokens by enforcing a blocking read and blocking write style. Time stamped tokens are appended to the queue with one of the two put() methods, both of which block on a write if the queue is full. Time stamped tokens are removed from the queue via the get() method. The get() method will throw a NoTokenException if it is invoked when the hasToken() method returns false.

    Each DDEReceiver is managed by a TimeKeeper. A single time keeper is assigned to manage all of the receivers of a given actor by keeping track of the actor's local notion of time. As tokens are consumed (returned by the get() method) in a receiver, the local time of the actor will advance to the value of the consumed token's time stamp. The hasToken() method of a receiver will return true only if the receiver's get() method will result in the minimum advancement of local time with respect to all of the receivers controlled by the TimeKeeper. If the get() method of multiple receivers will result in a minimum but identical local time advancement, then the hasToken() method of the receiver with the highest priority will return true (the others will return false).

    If a receiver with a nonnegative receiver time is empty, then the hasToken() method will perform a blocking read. Once, a token is available then hasToken() will return true or false according to the minimum time advancement rules cited in the preceding paragraph. Note that hasToken() blocks while get() does not block.

    DDEReceivers process certain events that are hidden from view by ports and actors. In particular, NullTokens have time stamps with a value of PrioritizedTimedQueue.IGNORE. NullTokens allow actors to communicate information on their local time advancement to neighboring actors without the need for an actual data exchange. NullTokens are passed at the receiver level and circumvent the Ptolemy II data typing mechanism.

    Time stamps of value PrioritizedTimedQueue.IGNORE are used to initiate execution in feedback cycles. If a receiver has a time stamp with value IGNORE, then it will not be considered when determining which receiver's get() method will result in the minimum local time advancement. Once a single token has been consumed by any other receiver, then the event with time stamp of value IGNORE will be removed. If all receivers have receiver times of IGNORE, then all such events will be removed.

    IMPORTANT: This class assumes that valid time stamps have non-negative values. Reserved negative values exist for special purposes: INACTIVE and IGNORE. These values are attributes of PrioritizedTimedQueue.

    Since:
    Ptolemy II 0.3
    Version:
    $Id$
    Author:
    John S. Davis II
    See Also:
    PrioritizedTimedQueue, DDEThread
    Pt.AcceptedRating:
    Green (kienhuis)
    Pt.ProposedRating:
    Green (davisj)
    • Constructor Detail

      • DDEReceiver

        public DDEReceiver()
        Construct an empty receiver with no container.
      • DDEReceiver

        public DDEReceiver​(IOPort container)
                    throws IllegalActionException
        Construct an empty receiver with the specified container.
        Parameters:
        container - The IOPort that contains this receiver.
        Throws:
        IllegalActionException - If this receiver cannot be contained by the proposed container.
      • DDEReceiver

        public DDEReceiver​(IOPort container,
                           int priority)
                    throws IllegalActionException
        Construct an empty receiver with the specified IOPort container and priority.
        Parameters:
        container - The IOPort that contains this receiver.
        priority - The priority of this receiver.
        Throws:
        IllegalActionException - If this receiver cannot be contained by the proposed container.
    • Method Detail

      • getDirector

        public DDEDirector getDirector()
        Return the director in charge of this receiver, or null if there is none.
        Returns:
        The director in charge of this receiver.
      • hasRoom

        public boolean hasRoom​(int tokens)
        Return true if the receiver has room for putting the given number of tokens into it (via the put() method). Returning true in this method should also guarantee that calling the put() method will not result in an exception.
        Specified by:
        hasRoom in interface Receiver
        Overrides:
        hasRoom in class PrioritizedTimedQueue
        Parameters:
        tokens - The number of tokens to put into the queue.
        Returns:
        True if the queue is not full; return false otherwise.
      • hasToken

        public boolean hasToken()
        Return true if the get() method of this receiver will return a token without throwing a NoTokenException. This method will perform a blocking read if this receiver is empty and has a nonnegative receiver time. Once the receiver is no longer empty, this method will return true only if this receiver is sorted first with respect to the other receivers contained by this receiver's actor. The sorting rules are found in ptolemy.domains.dde.kernel.ReceiverComparator.

        If at any point during this method this receiver is scheduled for termination, then throw a TerminateProcessException to cease execution of the actor that contains this receiver.

        Specified by:
        hasToken in interface Receiver
        Overrides:
        hasToken in class PrioritizedTimedQueue
        Returns:
        Return true if the get() method of this receiver will return a token without throwing a NoTokenException. Return false if the current thread is not a DDEThread.
      • hasToken

        public boolean hasToken​(int tokens)
        Return true if the receiver contains the given number of tokens that can be obtained by calling the get() method. Returning true in this method should also guarantee that calling the get() method will not result in an exception.
        Specified by:
        hasToken in interface Receiver
        Overrides:
        hasToken in class PrioritizedTimedQueue
        Parameters:
        tokens - The number of tokens to get from the queue.
        Returns:
        True if the queue has enough tokens.
      • isConnectedToBoundary

        public boolean isConnectedToBoundary()
                                      throws IllegalActionException
        Return true if this receiver is connected to the inside of a boundary port. A boundary port is an opaque port that is contained by a composite actor. If this receiver is connected to the inside of a boundary port, then return true; otherwise return false.
        Specified by:
        isConnectedToBoundary in interface ProcessReceiver
        Returns:
        True if this receiver is contained on the inside of a boundary port; return false otherwise.
        Throws:
        IllegalActionException
        See Also:
        BoundaryDetector
      • isConnectedToBoundaryOutside

        public boolean isConnectedToBoundaryOutside()
                                             throws IllegalActionException
        Return true if this receiver is connected to the outside of a boundary port. A boundary port is an opaque port that is contained by a composite actor. If this receiver is connected to the outside of a boundary port, then return true; otherwise return false.
        Specified by:
        isConnectedToBoundaryOutside in interface ProcessReceiver
        Returns:
        True if this receiver is connected to the outside of a boundary port; return false otherwise.
        Throws:
        IllegalActionException
        See Also:
        BoundaryDetector
      • isInsideBoundary

        public boolean isInsideBoundary()
        Return true if this receiver is contained on the inside of a boundary port. A boundary port is an opaque port that is contained by a composite actor. If this receiver is contained on the inside of a boundary port then return true; otherwise return false.
        Specified by:
        isInsideBoundary in interface ProcessReceiver
        Returns:
        True if this receiver is contained on the inside of a boundary port; return false otherwise.
        See Also:
        BoundaryDetector
      • isOutsideBoundary

        public boolean isOutsideBoundary()
        Return true if this receiver is contained on the outside of a boundary port. A boundary port is an opaque port that is contained by a composite actor. If this receiver is contained on the outside of a boundary port then return true; otherwise return false.
        Specified by:
        isOutsideBoundary in interface ProcessReceiver
        Returns:
        True if this receiver is contained on the outside of a boundary port; return false otherwise.
        See Also:
        BoundaryDetector
      • isProducerReceiver

        public boolean isProducerReceiver()
        Return true if this receiver is a producer receiver. A receiver is a producer receiver if it is contained on the inside or outside of a boundary port.
        Specified by:
        isProducerReceiver in interface ProcessReceiver
        Returns:
        True if this is a producer receiver; return false otherwise.
      • isReadBlocked

        public boolean isReadBlocked()
        Return a true or false to indicate whether there is a read block on this receiver or not, respectively.
        Specified by:
        isReadBlocked in interface ProcessReceiver
        Returns:
        a boolean indicating whether a read is blocked on this receiver or not.
      • isWriteBlocked

        public boolean isWriteBlocked()
        Return a true or false to indicate whether there is a write block on this receiver or not.
        Specified by:
        isWriteBlocked in interface ProcessReceiver
        Returns:
        A boolean indicating whether a write is blocked on this receiver or not.
      • put

        public void put​(Token token)
        Do a blocking write on the queue. Set the time stamp to be the current time of the sending actor. If the current time is greater than the completionTime of this receiver, then set the time stamp to INACTIVE and the token to null. If the queue is full, then inform the director that this receiver is blocking on a write and wait until room becomes available. When room becomes available, put the token and time stamp in the queue and inform the director that the block no longer exists. If at any point during this method this receiver is scheduled for termination, then throw a TerminateProcessException which will cease activity for the actor that contains this receiver.
        Specified by:
        put in interface Receiver
        Overrides:
        put in class PrioritizedTimedQueue
        Parameters:
        token - The token to put in the queue, or null to put no token.
        Throws:
        TerminateProcessException - If activity is scheduled to cease.
      • put

        public void put​(Token token,
                        Time time)
        Do a blocking write on the queue. Set the time stamp to be the time specified by the time parameter. If the specified time is greater than the completionTime of this receiver, then set the time stamp to INACTIVE and the token to null. If the queue is full, then inform the director that this receiver is blocking on a write and wait until room becomes available. When room becomes available, put the token and time stamp in the queue and inform the director that the block no longer exists. If at any point during this method this receiver is scheduled for termination, then throw a TerminateProcessException which will cease activity for the actor that contains this receiver.
        Overrides:
        put in class PrioritizedTimedQueue
        Parameters:
        token - The token to put in the queue, or null to put no token.
        time - The specified time stamp.
        Throws:
        TerminateProcessException - If activity is scheduled to cease.
      • requestFinish

        public void requestFinish()
        Schedule this receiver to terminate. After this method is called, a TerminateProcessException will be thrown during the next call to get() or put() of this class.
        Specified by:
        requestFinish in interface ProcessReceiver
      • reset

        public void reset()
        Reset local flags. The local flag of this receiver indicates whether this receiver is scheduled for termination. Resetting the termination flag will make sure that this receiver is not scheduled for termination.
        Specified by:
        reset in interface ProcessReceiver
        Specified by:
        reset in interface Receiver
        Overrides:
        reset in class PrioritizedTimedQueue