ptolemy.actor.process
Class MailboxBoundaryReceiver

java.lang.Object
  ptolemy.actor.AbstractReceiver
      ptolemy.actor.Mailbox
          ptolemy.actor.process.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: MailboxBoundaryReceiver.java 57040 2010-01-27 20:52:32Z cxh $

Author:

John S. Davis II

See Also:

Branch, BranchController

Accepted Rating:

Yellow (davisj)

Proposed Rating:

Green (mudit)

Field Summary

private BoundaryDetector	_boundaryDetector The boundary detector.
private ProcessDirector	_director The director in charge of this receiver.
private java.lang.Thread	_readPending Reference to a thread that is read blocked on this receiver.
private boolean	_terminate Flag indicating that termination has been requested.
private java.lang.Thread	_writePending Reference to a thread that is write blocked on this receiver.

Fields inherited from class ptolemy.actor.Mailbox

_token

Constructor Summary

MailboxBoundaryReceiver()
Construct an empty MailboxBoundaryReceiver with no container.

MailboxBoundaryReceiver(IOPort container)
Construct an empty MailboxBoundaryReceiver with the specified container.

Method Summary

Token	get() Get a token from this receiver.
ProcessDirector	getDirector() Return the director in charge of this receiver, or null if there is none.
boolean	isConnectedToBoundary() Return true if this receiver is connected to a boundary port.
boolean	isConnectedToBoundaryInside() Return true if this receiver is connected to the inside of an input boundary port; return false otherwise.
boolean	isConnectedToBoundaryOutside() Return true if this receiver is connected to the outside of an output boundary port; return false otherwise.
boolean	isConsumerReceiver() Return true if this is a consumer receiver; return false otherwise.
boolean	isInsideBoundary() Return true if this receiver is contained on the inside of a boundary port.
boolean	isOutsideBoundary() Return true if this receiver is contained on the outside of a boundary port.
boolean	isProducerReceiver() Return true if this is a producer receiver; return false otherwise.
boolean	isReadBlocked() Return a true or false to indicate whether there is a read block on this receiver or not, respectively.
boolean	isWriteBlocked() Return a true or false to indicate whether there is a write block on this receiver or not.
void	put(Token token) Put a token into this receiver.
void	requestFinish() Set a local flag requesting that execution of the actor containing this receiver discontinue.
void	reset() Reset the local flags of this receiver.
void	setContainer(IOPort port) Set the container.

Methods inherited from class ptolemy.actor.Mailbox

clear, elementList, hasRoom, hasRoom, hasToken, hasToken

Methods inherited from class ptolemy.actor.AbstractReceiver

getArray, getContainer, getCurrentTime, getModelTime, isKnown, putArray, putArrayToAll, putToAll, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Receiver

clear, elementList, getArray, getContainer, hasRoom, hasRoom, hasToken, hasToken, isKnown, putArray, putArrayToAll, putToAll

Field Detail

_boundaryDetector

private BoundaryDetector _boundaryDetector

The boundary detector.

_director

private ProcessDirector _director

The director in charge of this receiver.

_readPending

private java.lang.Thread _readPending

Reference to a thread that is read blocked on this receiver.

_terminate

private boolean _terminate

Flag indicating that termination has been requested.

_writePending

private java.lang.Thread _writePending

Reference to a thread that is write blocked on this receiver.

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

isConnectedToBoundaryInside

public boolean isConnectedToBoundaryInside()
                                    throws InvalidStateException,
                                           IllegalActionException

Return true if this receiver is connected to the inside of an input boundary port; return false otherwise. A boundary port is an opaque port that is contained by a composite actor. This method is not synchronized so the caller should be.

Specified by:

isConnectedToBoundaryInside in interface ProcessReceiver

Returns:

True if this receiver is connected to the inside of a boundary port; return false otherwise.

Throws:

IllegalActionException

InvalidStateException

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

reset

public void reset()

Reset the local flags of this receiver. Use this method when restarting execution.

Specified by:

reset in interface ProcessReceiver

Specified by:

reset in interface Receiver

Overrides:

reset in class AbstractReceiver

setContainer

public void setContainer(IOPort port)
                  throws IllegalActionException

Set the container. This overrides the base class to record the director.

Specified by:

setContainer in interface Receiver

Overrides:

setContainer in class AbstractReceiver

Parameters:

port - The container.

Throws:

IllegalActionException - If the container is not of an appropriate subclass of IOPort, or if the container's director is not an instance of ProcessDirector.

See Also:

AbstractReceiver.getContainer()