ptolemy.actor.process

Interface ProcessReceiver

All Superinterfaces:

Receiver

All Known Implementing Classes:

CSPReceiver, DDEReceiver, MailboxBoundaryReceiver, MetroIIPNQueueReceiver, PNQueueReceiver, RendezvousReceiver

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$

Author:

Neil Smyth, Mudit Goel, John S. Davis II

See Also:

BoundaryDetector

Pt.AcceptedRating:

Yellow (mudit)

Pt.ProposedRating:

Green (mudit)

Method Summary

Modifier and Type	Method and Description
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 whether this receiver is read blocked.
boolean	isWriteBlocked() Determine whether this receiver is write blocked.
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, elementList, get, getArray, getContainer, hasRoom, hasRoom, hasToken, hasToken, isKnown, put, putArray, putArrayToAll, putToAll, setContainer

Method Detail

isConnectedToBoundary

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.

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.

Throws:

InvalidStateException - If thrown by the boundary detector.

IllegalActionException - If thrown by the boundary detector.

See Also:

BoundaryDetector

isConnectedToBoundaryInside

boolean isConnectedToBoundaryInside()
                             throws InvalidStateException,
                                    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.

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.

Throws:

IllegalActionException - If thrown by the boundary detector.

InvalidStateException - If thrown by the boundary detector.

See Also:

BoundaryDetector

isConnectedToBoundaryOutside

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.

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.

Throws:

IllegalActionException - If thrown by the boundary detector.

See Also:

BoundaryDetector

isConsumerReceiver

boolean isConsumerReceiver()
                    throws IllegalActionException

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.

Throws:

IllegalActionException - If thrown by the boundary detector.

isInsideBoundary

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

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

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

boolean isReadBlocked()

Determine whether this receiver is read blocked.

Returns:

True if this receiver is read blocked and false otherwise.

isWriteBlocked

boolean isWriteBlocked()

Determine whether this receiver is write blocked.

Returns:

True if this receiver is write blocked and false otherwise.

requestFinish

void requestFinish()

Set a local flag requesting that the simulation be finished.

reset

void reset()

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

Specified by:

reset in interface Receiver