ptolemy.actor.process
Interface ProcessReceiver

All Superinterfaces:
Receiver
All Known Implementing Classes:
CSPReceiver, DDEReceiver, MailboxBoundaryReceiver, PNQueueReceiver

public interface ProcessReceiver
extends Receiver

A ProcessReceiver is an interface for receivers in the process oriented domains. It adds methods to the Receiver interface for setting flags that indicate whether a termination of the simulation has been requested. In addition, methods are available to accommodate hierarchical heterogeneity via composite actors.

In process oriented domains, simulations are normally ended on the detection of a deadlock. During a deadlock, processes or the corresponding threads are normally waiting on a call to some methods (for reading or writing) on a receiver. To terminate or end the simulation, these methods should either return or throw an exception to inform the processes that they should terminate themselves. For this a method requestFinish() is defined. This method would set a local flag in the receivers and wake up all the processes waiting on some call to the receiver. On waking up these processes would see that the termination flag set and behave accordingly. A sample implementation is
public synchronized void requestFinish() { _terminate = true; notifyAll(); }

To accommodate hierarchical heterogeneity, an instantiation of ProcessReceiver must be able to determine its topological location with respect to boundary ports. A boundary port is an opaque port that is contained by a composite actor. This ability is enforced with the isConnectedToBoundary(), isConnectedToBoundaryOutside(), isConnectedToBoundaryInside(), isInsideBoundary() and isOutsideBoundary() methods. For convenience, the BoundaryDetector class is available to to simplify the implementation of these methods.

Blocking reads and writes are accommodated via the get(Branch) and put(Token, Branch) methods. In cases where a branch attempts to get data from or put data into a process receiver, it calls, respectively, these methods by passing itself as an argument. The process receiver then knows to register any blocks with the branch rather than with a director as is occurs in non-composite cases.

Note that it is not necessary for an implementation of ProcessReceiver to be used in the ports of an opaque composite actor. It is perfectly fine for a ProcessReceiver implementation 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 0.2
Version:
$Id: ProcessReceiver.java,v 1.38 2004/04/13 03:11:11 cxh Exp $
Author:
Neil Smyth, Mudit Goel, John S. Davis II
See Also:
BoundaryDetector
Accepted Rating:
Yellow (mudit)
Proposed Rating:
Green (mudit)

Method Summary
 Token get(Branch controllingBranch)
          Get a token from this receiver and pass in a branch object as an argument.
 boolean isConnectedToBoundary()
          Return true if this receiver is connected to the inside of a boundary port.
 boolean isConnectedToBoundaryInside()
          Return true if this receiver is connected to the inside of a boundary port.
 boolean isConnectedToBoundaryOutside()
          Return true if this receiver is connected to the outside of a boundary port.
 boolean isConsumerReceiver()
          Return true if this receiver is a consumer receiver.
 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 receiver is a producer receiver.
 boolean isReadBlocked()
          Determine if this receiver is read blocked.
 boolean isWriteBlocked()
          Determine if this receiver is write blocked.
 void put(Token token, Branch controllingBranch)
          Put a token into this receiver and pass in a branch object as an argument.
 void requestFinish()
          Set a local flag requesting that the simulation be finished.
 void reset()
          Reset the local flags of this receiver.
 
Methods inherited from interface ptolemy.actor.Receiver
clear, get, getArray, getContainer, hasRoom, hasRoom, hasToken, hasToken, isKnown, put, putArray, setContainer
 

Method Detail

get

public Token get(Branch controllingBranch)
Get a token from this receiver and pass in a branch object as an argument. This method can accommodate blocking reads at the boundary of composite actors. If the branch argument is not null it is assumed that the receiver is at or connected to the boundary of a composite actor and any blocks are registered with the branch. If the branch is null than the receiver is not associated with a composite actor boundary and blocks are registered with a director.


isConnectedToBoundary

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

It is suggested that this method be implemented using the BoundaryDetector class although such an implementation is not necessary.

Returns:
True if this receiver is contained on the inside of a boundary port; return false otherwise.
See Also:
BoundaryDetector

isConnectedToBoundaryInside

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

It is suggested that this method be implemented using the BoundaryDetector class although such an implementation is not necessary.

Returns:
True if this receiver is contained on 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 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.

It is suggested that this method be implemented using the BoundaryDetector class although such an implementation is not necessary.

Returns:
True if this receiver is contained on the outside of a boundary port; return false otherwise.
See Also:
BoundaryDetector

isConsumerReceiver

public boolean isConsumerReceiver()
Return true if this receiver is a consumer receiver. A process receiver is a consumer receiver if it is connected to a boundary port.

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.

It is suggested that this method be implemented using the BoundaryDetector class although such an implementation is not necessary.

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.

It is suggested that this method be implemented using the BoundaryDetector class although such an implementation is not necessary.

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 process receiver is a producer receiver if it is contained on the inside or outside of a boundary port.

Returns:
True if this is a producer receiver; return false otherwise.

isReadBlocked

public boolean isReadBlocked()
Determine if this receiver is read blocked.

Returns:
True if this receiver is read blocked; return false otherwise.

isWriteBlocked

public boolean isWriteBlocked()
Determine if this receiver is write blocked.

Returns:
True if this receiver is write blocked; return false otherwise.

put

public void put(Token token,
                Branch controllingBranch)
Put a token into this receiver and pass in a branch object as an argument. This method can accommodate blocking writes at the boundary of composite actors. If the branch argument is not null it is assumed that the receiver is at or connected to the boundary of a composite actor and any blocks are registered with the branch. If the branch is null than the receiver is not associated with a composite actor boundary and blocks are registered with a director.


requestFinish

public void requestFinish()
Set a local flag requesting that the simulation be finished.


reset

public void reset()
Reset the local flags of this receiver. Use this method when restarting execution.