ptolemy.actor.process
Class MailboxBoundaryReceiver

java.lang.Object
  extended byptolemy.actor.AbstractReceiver
      extended byptolemy.actor.Mailbox
          extended byptolemy.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,v 1.42 2004/04/13 03:11:05 cxh Exp $
Author:
John S. Davis II
See Also:
Branch, BranchController
Accepted Rating:
Yellow (davisj)
Proposed Rating:
Green (mudit)

Field Summary
 
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.
 Token get(Branch branch)
          Get a token from the receiver and use the specified branch object to manage the method invocation.
 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 true if this receiver is read blocked; return false otherwise.
 boolean isWriteBlocked()
          Return true if this receiver is write blocked; return false otherwise.
 void prepareToBlock(Branch branch)
          Prepare to register a block.
 void put(Token token)
          Put a token into this receiver.
 void put(Token token, Branch branch)
          Put a token in the receiver and use the specified branch object to manage the method invocation.
 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 wakeUpBlockedPartner()
          Unblock this receiver and register this new state with either the monitoring branch or the local director.
 
Methods inherited from class ptolemy.actor.Mailbox
clear, hasRoom, hasRoom, hasToken, hasToken
 
Methods inherited from class ptolemy.actor.AbstractReceiver
getArray, getContainer, getCurrentTime, isKnown, putArray, setContainer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface ptolemy.actor.Receiver
clear, getArray, getContainer, hasRoom, hasRoom, hasToken, hasToken, isKnown, putArray, setContainer
 

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.

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.

get

public Token get(Branch branch)
Get a token from the receiver and use the specified branch object to manage the method invocation. If the receiver is empty then block until a token becomes available. If the specified branch object is non-null then use the branch object to coordinate the blocking read with a branch controller. If the specified branch object is null then use the local director to coordinate the block. If this receiver is terminated during the execution of this method, then throw a TerminateProcessException.

Specified by:
get in interface ProcessReceiver
Parameters:
branch - The Branch managing execution of this method.
Returns:
The token contained by this receiver.

isConnectedToBoundary

public boolean isConnectedToBoundary()
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.
See Also:
BoundaryDetector

isConnectedToBoundaryInside

public boolean isConnectedToBoundaryInside()
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.
See Also:
BoundaryDetector

isConnectedToBoundaryOutside

public boolean isConnectedToBoundaryOutside()
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.
See Also:
BoundaryDetector

isConsumerReceiver

public boolean isConsumerReceiver()
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.

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 true if this receiver is read blocked; return false otherwise.

Specified by:
isReadBlocked in interface ProcessReceiver
Returns:
True if this receiver is read blocked; return false otherwise.

isWriteBlocked

public boolean isWriteBlocked()
Return true if this receiver is write blocked; return false otherwise.

Specified by:
isWriteBlocked in interface ProcessReceiver
Returns:
True if this receiver is write blocked; return false otherwise.

prepareToBlock

public void prepareToBlock(Branch branch)
Prepare to register a block. If the branch object specified as a parameter is non-null then register the block with the branch. If the branch object specified as a parameter is null then register the block with the local director.

Parameters:
branch - The Branch managing execution of this method.

put

public void put(Token token,
                Branch branch)
Put a token in the receiver and use the specified branch object to manage the method invocation. If the receiver is full (contains a token) then block until room becomes available. If the specified branch object is non-null then use the branch object to coordinate the blocking read with a branch controller. If the specified branch object is null then use the local director to coordinate the block. If this receiver is terminated during the execution of this method, then throw a TerminateProcessException.

Specified by:
put in interface ProcessReceiver
Parameters:
branch - The Branch managing execution of this method.
token - The token to be placed in this receiver.

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.

Specified by:
put in interface Receiver
Overrides:
put in class Mailbox
Parameters:
token - The token being placed in this receiver.

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

wakeUpBlockedPartner

public void wakeUpBlockedPartner()
Unblock this receiver and register this new state with either the monitoring branch or the local director. If there is no blocked branch waiting, then register the new state with the local director; otherwise, register the new state with the blocked branch.