Class RendezvousReceiver

  • All Implemented Interfaces:
    ProcessReceiver, Receiver

    public class RendezvousReceiver
    extends AbstractReceiver
    implements ProcessReceiver
    Receiver for rendezvous style communication. In the rendezvous domain, all communication is via synchronous message passing, so both the the sending and receiving processes need to rendezvous at the receiver. For rendezvous, the receiver is the key synchronization point. It is assumed each receiver has at most one thread trying to send to it and at most one thread trying to receive from it at any one time. The receiver performs the synchronization necessary for simple rendezvous (get() and put() operations). This receiver is based on the CSPReceiver class by John S. Davis II, Thomas Feng, Edward A. Lee, Neil Smyth, and Yang Zhao.
    Since:
    Ptolemy II 5.1
    Version:
    $Id$
    Author:
    Thomas Feng
    Pt.AcceptedRating:
    Green (tfeng)
    Pt.ProposedRating:
    Green (tfeng)
    • Constructor Detail

      • RendezvousReceiver

        public RendezvousReceiver()
        Construct a RendezvousReceiver with no container.
      • RendezvousReceiver

        public RendezvousReceiver​(IOPort container)
                           throws IllegalActionException
        Construct a RendezvousReceiver with the specified container.
        Parameters:
        container - The port containing this receiver.
        Throws:
        IllegalActionException - If this receiver cannot be contained by the proposed container.
    • Method Detail

      • get

        public Token get()
                  throws TerminateProcessException
        Get a token from this receiver. This method does not return until the rendezvous has been completed. This method is internally synchronized on the director.
        Specified by:
        get in interface Receiver
        Specified by:
        get in class AbstractReceiver
        Returns:
        The token contained by this receiver.
        Throws:
        TerminateProcessException - If the actor to which this receiver belongs has been terminated while still running i.e it was not allowed to run to completion.
      • getFromAll

        public static Token[][] getFromAll​(Receiver[][] receivers,
                                           RendezvousDirector director)
                                    throws TerminateProcessException
        Get from all receivers in the specified array. This method does not return until all the gets are complete.
        Parameters:
        receivers - The receivers, which are assumed to all be instances of RendezvousReceiver.
        director - The director, on which this method synchronizes.
        Returns:
        An array of token arrays, where the structure of the array is the same as the structure of the specified array of receivers. Note that if the receivers argument has any null values in the array of arrays, then so will the returned array or arrays.
        Throws:
        TerminateProcessException - If the actor to which this receiver belongs is to be terminated.
      • getFromAny

        public static Token getFromAny​(Receiver[][] receivers,
                                       RendezvousDirector director)
                                throws TerminateProcessException
        Get from any receiver in the specified array. This method does not return until one of the gets is complete.
        Parameters:
        receivers - The receivers, which are assumed to all be instances of RendezvousReceiver.
        director - The director, on which this method synchronizes.
        Returns:
        A token from one of the receivers.
        Throws:
        TerminateProcessException - If the actor to which this receiver belongs is to be terminated.
      • getFromAnyPutToAll

        public static void getFromAnyPutToAll​(Receiver[][] getReceivers,
                                              Receiver[][] putReceivers,
                                              RendezvousDirector director)
                                       throws IllegalActionException,
                                              TerminateProcessException
        Get from any receiver in the getReceivers array, and put the token received to all receivers in putReceivers array. The put and get are to be accomplished simultaneously in a rendezvous. This method does not return until both the get and put are complete.
        Parameters:
        getReceivers - The receivers, which are assumed to all be instances of RendezvousReceiver, to get tokens from.
        putReceivers - The receivers, which are assumed to all be instances of RendezvousReceiver, to put tokens to.
        director - The director, on which this method synchronizes.
        Throws:
        IllegalActionException - If the token is not acceptable to one of the ports (e.g., wrong type).
        TerminateProcessException - If the actor to which this receiver belongs is to be terminated.
      • hasRoom

        public boolean hasRoom()
        Return true. This method returns true in all cases to indicate that the next call to put() will succeed without throwing a NoRoomException, as indeed it will, even if not right away. Note that if this were to return true only if a rendezvous was pending, then polymorphic actors would busy wait.
        Specified by:
        hasRoom in interface Receiver
        Specified by:
        hasRoom in class AbstractReceiver
        Returns:
        True.
      • hasRoom

        public boolean hasRoom​(int tokens)
        Return true. This method returns true in all cases to indicate that any number of calls to put() will succeed without throwing a NoRoomException, as indeed they will, even if not right away. Note that if this were to return true only if a rendezvous was pending, then polymorphic actors would busy wait.
        Specified by:
        hasRoom in interface Receiver
        Specified by:
        hasRoom in class AbstractReceiver
        Parameters:
        tokens - Ignored by this method.
        Returns:
        True.
      • hasToken

        public boolean hasToken()
        Return true. This method returns true in all cases to indicate that the next call to get() will succeed without throwing a NoTokenException, as indeed it will, even if not right away. Note that if this were to return true only if a rendezvous was pending, then polymorphic actors would busy wait.
        Specified by:
        hasToken in interface Receiver
        Specified by:
        hasToken in class AbstractReceiver
        Returns:
        True.
      • hasToken

        public boolean hasToken​(int tokens)
        Return true. This method returns true in all cases to indicate that any number of calls to get() will succeed without throwing a NoTokenException, as indeed they will, even if not right away. Note that if this were to return true only if a rendezvous was pending, then polymorphic actors would busy wait.
        Specified by:
        hasToken in interface Receiver
        Specified by:
        hasToken in class AbstractReceiver
        Parameters:
        tokens - Ignored by this method.
        Returns:
        True.
      • 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 connected to 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 on an outside or an inside boundary.
        Specified by:
        isProducerReceiver in interface ProcessReceiver
        Returns:
        True if this is a producer receiver; return false otherwise.
      • isReadBlocked

        public boolean isReadBlocked()
        Return true if there is a get or a conditional receive waiting on this receiver.
        Specified by:
        isReadBlocked in interface ProcessReceiver
        Returns:
        True if a read is pending on this receiver.
      • isWriteBlocked

        public boolean isWriteBlocked()
        Return true if there is either a put or a conditional send waiting on this receiver.
        Specified by:
        isWriteBlocked in interface ProcessReceiver
        Returns:
        A boolean indicating whether a write is pending on this receiver.
      • put

        public void put​(Token token)
                 throws IllegalActionException,
                        TerminateProcessException
        Put a token into the mailbox receiver. This method does not return until the rendezvous is complete. This method is internally synchronized on the director.
        Specified by:
        put in interface Receiver
        Specified by:
        put in class AbstractReceiver
        Parameters:
        token - The token, or null to not put any token.
        Throws:
        IllegalActionException - If the token is not acceptable to the port (e.g., wrong type).
        TerminateProcessException - If the actor to which this receiver belongs has been terminated while still running i.e it was not allowed to run to completion.
      • putArrayToAll

        public void putArrayToAll​(Token[] tokens,
                                  int numberOfTokens,
                                  Receiver[] receivers)
                           throws NoRoomException,
                                  IllegalActionException,
                                  TerminateProcessException
        Put a sequence of tokens to all receivers in the specified array. This method sequentially calls putToAll() for each token in the tokens array.
        Specified by:
        putArrayToAll in interface Receiver
        Overrides:
        putArrayToAll in class AbstractReceiver
        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.
        TerminateProcessException - If the actor to which this receiver belongs has been terminated while still running i.e it was not allowed to run to completion.
      • putToAll

        public void putToAll​(Token token,
                             Receiver[] receivers,
                             RendezvousDirector director)
                      throws IllegalActionException,
                             TerminateProcessException
        Put to all receivers in the specified array. This method does not return until all the puts are complete. This method differs from its counterpart in the superclass in that it puts the token to all receivers in an atomic step. The method in the superclass puts the token to one receiver in the receiver array at a time.
        Parameters:
        token - The token to put, or null to not put any token.
        receivers - The receivers, which are assumed to all be instances of RendezvousReceiver.
        director - The director, on which this method synchronizes.
        Throws:
        IllegalActionException - If the token is not acceptable to one of the ports (e.g., wrong type).
        TerminateProcessException - If the actor to which this receiver belongs is to be terminated.
      • putToAll

        public static void putToAll​(Token[][] tokens,
                                    Receiver[][] receivers,
                                    RendezvousDirector director)
                             throws IllegalActionException,
                                    TerminateProcessException
        Put to all receivers in the specified array. This method does not return until all the puts are complete. The tokens argument can have fewer tokens than receivers argument has receivers. If only one token is given (the argument has dimension [1][1]), then that one token is copied to all destination receivers (with possible type changes). If only one token in each dimension is given, then that one token is copied to all destination receivers in the corresponding dimension of the receivers array.
        Parameters:
        tokens - The tokens to put.
        receivers - * The receivers, which are assumed to all be instances of RendezvousReceiver.
        director - The director, on which this method synchronizes.
        Throws:
        IllegalActionException - If the token is not acceptable to one of the ports (e.g., wrong type).
        TerminateProcessException - If the actor to which this receiver belongs is to be terminated.
      • putToAny

        public static void putToAny​(Token token,
                                    Receiver[][] receivers,
                                    RendezvousDirector director)
                             throws IllegalActionException,
                                    TerminateProcessException
        Put the specified token to any receiver in the specified array. This method does not return until one of the puts is complete.
        Parameters:
        token - The token to put.
        receivers - The receivers, which are assumed to all be instances of RendezvousReceiver.
        director - The director, on which this method synchronizes.
        Throws:
        IllegalActionException - If the token is not acceptable to one of the ports (e.g., wrong type).
        TerminateProcessException - If the actor to which this receiver belongs is to be terminated.
      • requestFinish

        public void requestFinish()
        The model has finished executing, so set a flag so that the next time an actor tries to get or put it gets a TerminateProcessException which will cause it to finish.
        Specified by:
        requestFinish in interface ProcessReceiver
      • waitForChange

        public static void waitForChange​(RendezvousDirector director)
                                  throws TerminateProcessException
        Wait on the specified director. This is not synchronized on the specified director, so the called should be.
        Parameters:
        director - The director on which to wait.
        Throws:
        TerminateProcessException - If a finish has been requested of the specified director, or if the calling thread is interrupted while waiting.
      • _commitRendezvous

        protected static void _commitRendezvous​(java.util.Set receivers,
                                                RendezvousDirector director)
        Commit the rendezvous formed by the set of receivers that agree to send and receive at the same time.
        Parameters:
        receivers - The receivers that participate in the rendezvous.
        director - The director.
        See Also:
        _receiversReadyToCommit(Receiver[][], boolean)
      • _getDirector

        protected RendezvousDirector _getDirector()
        Return the director that is controlling the execution of this model. If this receiver is an inside receiver, then it is the director of the container (actor) of the container (port). Otherwise, it is the executive director of the container (actor) of the container (port).
        Returns:
        The RendezvousDirector controlling this model.
      • _receiversReadyToCommit

        protected static java.util.Set _receiversReadyToCommit​(Receiver[][] receivers,
                                                               boolean isPut)
        Get the receivers that are ready to form a rendezvous according to the rendezvous semantics. If no rendezvous can be formed starting for the given array of receivers, null is returned.
        Parameters:
        receivers - The array of receivers to be put to or get from.
        isPut - If true, the rendezvous is to put tokens to the receivers; if false, the rendezvous is to get tokens from the receivers.
        Returns:
        A set of receivers that participate in the rendezvous if it can be formed, or null if no rendezvous can be formed.
        See Also:
        _commitRendezvous(Set, RendezvousDirector)