Class MailboxBoundaryReceiver

  • All Implemented Interfaces:
    ProcessReceiver, Receiver

    public class MailboxBoundaryReceiver
    extends Mailbox
    implements ProcessReceiver
    A process receiver that stores tokens via a mailbox and can be used by composite actors. This receiver extends the functionality of the mailbox receiver found in the actor package in two key ways. First it facilitates blocking reads and writes. If a read (a call to get()) is attempted when this mailbox is empty then the call will block until a token is placed in the mailbox. Similarly if a write (a call to put()) is attempted when this mailbox is full (has a token) then the call will block until the token is removed from the mailbox.

    The second key feature of this mailbox receiver is that it can be used by opaque composite actors operating in process-oriented models of computation. Indeed the name "MailboxBoundaryReceiver" is used to indicate that this receiver can be contained on the boundary of an opaque composite actor. The get() and put() methods of mailbox boundary receiver can be invoked by a Branch object. In such cases any blocks that occur are registered with the calling branch. The branch will then serve as a proxy by communicating to the director through the branch controller.

    Note that it is not necessary for a mailbox boundary receiver to be used in the ports of an opaque composite actor. It is perfectly fine for a mailbox boundary receiver to be used in the ports of an atomic actor. In such cases the get() and put() methods are called without the use of a branch object. If blocking reads or writes occur they are registered with the controlling director without the need for a branch or branch controller.

    Since:
    Ptolemy II 1.0
    Version:
    $Id$
    Author:
    John S. Davis II
    See Also:
    Branch, BranchController
    Pt.AcceptedRating:
    Yellow (davisj)
    Pt.ProposedRating:
    Green (mudit)
    • Constructor Detail

      • MailboxBoundaryReceiver

        public MailboxBoundaryReceiver()
        Construct an empty MailboxBoundaryReceiver with no container.
      • MailboxBoundaryReceiver

        public MailboxBoundaryReceiver​(IOPort container)
                                throws IllegalActionException
        Construct an empty MailboxBoundaryReceiver with the specified container.
        Parameters:
        container - The container.
        Throws:
        IllegalActionException - If the container cannot contain this receiver.
    • Method Detail

      • get

        public Token get()
        Get a token from this receiver. If the receiver is empty then block until a token becomes available. Use the local director to manage blocking reads that occur. If this receiver is terminated during the execution of this method, then throw a TerminateProcessException.
        Specified by:
        get in interface Receiver
        Overrides:
        get in class Mailbox
        Returns:
        The token contained by this receiver.
      • getDirector

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

        public boolean isConnectedToBoundary()
                                      throws IllegalActionException
        Return true if this receiver is connected to a boundary port. A boundary port is an opaque port that is contained by a composite actor. If this receiver is connected to a boundary port, then return true; otherwise return false. This method is not synchronized so the caller should be.
        Specified by:
        isConnectedToBoundary in interface ProcessReceiver
        Returns:
        True if this receiver is connected to 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 an output boundary port; return false otherwise. 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 false. This method is not synchronized so the caller should be.
        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
      • isConsumerReceiver

        public boolean isConsumerReceiver()
                                   throws IllegalActionException
        Return true if this is a consumer receiver; return false otherwise. A consumer receiver is defined as a receiver that is connected to a boundary port.
        Specified by:
        isConsumerReceiver in interface ProcessReceiver
        Returns:
        True if this is a consumer receiver; return false otherwise.
        Throws:
        IllegalActionException
      • 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. This method is not synchronized so the caller should be.
        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. This method is not synchronized so the caller should be.
        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 is a producer receiver; return false otherwise. A producer receiver is defined as a receiver that is connected to 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)
        Put a token into this receiver. If the receiver is full (contains a token) then block until room becomes available. Use the local director to manage blocking writes that occur. If this receiver is terminated during the execution of this method, then throw a TerminateProcessException. If the specified token is null, this method does nothing.
        Specified by:
        put in interface Receiver
        Overrides:
        put in class Mailbox
        Parameters:
        token - The token being placed in this receiver, or null to do nothing.
      • requestFinish

        public void requestFinish()
        Set a local flag requesting that execution of the actor containing this receiver discontinue.
        Specified by:
        requestFinish in interface ProcessReceiver