ptolemy.domains.pn.kernel

Class PNQueueReceiver

java.lang.Object

ptolemy.actor.AbstractReceiver

ptolemy.actor.QueueReceiver

ptolemy.domains.pn.kernel.PNQueueReceiver

All Implemented Interfaces:

ProcessReceiver, Receiver

Direct Known Subclasses:

MetroIIPNQueueReceiver

public class PNQueueReceiver
extends QueueReceiver
implements ProcessReceiver

A receiver with a FIFO queue that blocks the calling process on a read if the FIFO queue is empty and on a write if the queue is full. Blocking read provides the basic functionality of a FIFO channel in the process networks model of computation. Blocking write supports the implementation suggested by Parks for bounded memory execution of process networks.

Tokens are appended to the queue with the put() method, which blocks on a write if the queue is full. Tokens are removed from the queue with the get() method, which blocks on a read if the queue is empty. In case a process blocks on a read or a write, the receiver informs the director about the same. The receiver also unblocks processes blocked on a read or a write. In case a process is blocked on a read (read-blocked), it is unblocked on availability of a token. If a process is blocked on a write (write-blocked), it is unblocked on the availability of room in the queue and informs the director of the same.

This class is also responsible for pausing or terminating a process that tries to read from or write to the receiver. In case of termination, the receiver throws a TerminateProcessException when a process tries to read from or write to the receiver. This terminates the process. In case of pausing, the receiver suspends the process when it tries to read from or write to the receiver and resumes it only after a request to resume the process has been received.g

Since:

Ptolemy II 0.2

Version:

$Id$

Author:

Mudit Goel, John S. Davis II, Edward A. Lee, Xiaowen Xin

See Also:

QueueReceiver, QueueReceiver

Pt.AcceptedRating:

Red (hyzheng)

Pt.ProposedRating:

Yellow (eal)

Field Summary

Fields

Modifier and Type	Field and Description
protected BoundaryDetector	_boundaryDetector A BoundaryDetector determines the topological relationship of a Receiver with respect to boundary ports.
protected PNDirector	_director The director in charge of this receiver.
protected java.lang.Thread	_readPending Reference to a thread that is read blocked on this receiver.
protected boolean	_terminate Flag indicating whether finish has been requested.
protected java.lang.Thread	_writePending Reference to a thread that is write blocked on this receiver.

Fields inherited from class ptolemy.actor.QueueReceiver

_queue, INFINITE_CAPACITY

Constructor Summary

Constructors

Constructor and Description
PNQueueReceiver() Construct an empty receiver with no container.
PNQueueReceiver(IOPort container) Construct an empty receiver with the specified container.

Method Summary

Modifier and Type	Method and Description
Token	get() Get a token from this receiver.
PNDirector	getDirector() Return the director in charge of this receiver, or null if there is none.
boolean	hasRoom() Return true, since a channel in the Kahn process networks model of computation is of infinite capacity and always has room.
boolean	hasRoom(int tokens) Return true, since a channel in the Kahn process networks model of computation is of infinite capacity and always has room.
boolean	hasToken() Return true, since a call to the get() method of the receiver will always return a token if the call to get() ever returns.
boolean	hasToken(int tokens) Return true, since a call to the get() method of the receiver will always return a token if the call to get() ever returns.
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 connected to the boundary.
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 at a boundary.
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 on the queue contained in this receiver.
void	requestFinish() Set a flag in the receiver to indicate the onset of termination.
void	reset() Reset the state variables in the receiver.
void	setContainer(IOPort port) Set the container.

Methods inherited from class ptolemy.actor.QueueReceiver

clear, elementList, elements, get, getCapacity, getHistoryCapacity, historyElementList, historyElements, historySize, setCapacity, setHistoryCapacity, size

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, isKnown, putArray, putArrayToAll, putToAll

Field Detail

_director

protected PNDirector _director

The director in charge of this receiver.

_readPending

protected java.lang.Thread _readPending

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

_writePending

protected java.lang.Thread _writePending

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

_terminate

protected boolean _terminate

Flag indicating whether finish has been requested.

_boundaryDetector

protected BoundaryDetector _boundaryDetector

A BoundaryDetector determines the topological relationship of a Receiver with respect to boundary ports.

Constructor Detail

PNQueueReceiver

public PNQueueReceiver()

Construct an empty receiver with no container.

PNQueueReceiver

public PNQueueReceiver(IOPort container)
                throws IllegalActionException

Construct an empty receiver with the specified container.

Parameters:

container - The container of this receiver.

Throws:

IllegalActionException - If the container does not accept this receiver.

Method Detail

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 PNDirector.

See Also:

AbstractReceiver.getContainer()

get

public Token get()

Get a token from this receiver. If the receiver is empty then block until a token becomes available. 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 QueueReceiver

Returns:

The token contained by this receiver.

getDirector

public PNDirector getDirector()

Return the director in charge of this receiver, or null if there is none.

Returns:

The director in charge of this receiver.

hasRoom

public boolean hasRoom()

Return true, since a channel in the Kahn process networks model of computation is of infinite capacity and always has room.

Specified by:

hasRoom in interface Receiver

Overrides:

hasRoom in class QueueReceiver

Returns:

True.

hasRoom

public boolean hasRoom(int tokens)

Return true, since a channel in the Kahn process networks model of computation is of infinite capacity and always has room.

Specified by:

hasRoom in interface Receiver

Overrides:

hasRoom in class QueueReceiver

Parameters:

tokens - The number of tokens, which is ignored in this method.

Returns:

True.

hasToken

public boolean hasToken()

Return true, since a call to the get() method of the receiver will always return a token if the call to get() ever returns.

Specified by:

hasToken in interface Receiver

Overrides:

hasToken in class QueueReceiver

Returns:

True.

hasToken

public boolean hasToken(int tokens)

Return true, since a call to the get() method of the receiver will always return a token if the call to get() ever returns.

Specified by:

hasToken in interface Receiver

Overrides:

hasToken in class QueueReceiver

Parameters:

tokens - The number of tokens, which is ignored in this method.

Returns:

True.

isConnectedToBoundary

public 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.

Specified by:

isConnectedToBoundary in interface ProcessReceiver

Returns:

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

Throws:

IllegalActionException - If thrown by the boundary detector.

See Also:

BoundaryDetector

isConnectedToBoundaryInside

public 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.

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 - If thrown by the boundary detector.

InvalidStateException - If thrown by the boundary detector.

See Also:

BoundaryDetector

isConnectedToBoundaryOutside

public 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.

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 - If thrown by the boundary detector.

See Also:

BoundaryDetector

isConsumerReceiver

public boolean isConsumerReceiver()
                           throws IllegalActionException

Return true if this receiver is connected to the boundary. That is, it is in an input port that is connected on the outside to the inside of an input port, or it is on the inside of an output port that is connected on the outside to an input port higher in the hierarchy.

Specified by:

isConsumerReceiver in interface ProcessReceiver

Returns:

True if this is connected to the boundary.

Throws:

IllegalActionException - If thrown by the boundary detector.

See Also:

isConnectedToBoundary()

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.

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.

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 receiver is at a boundary.

Specified by:

isProducerReceiver in interface ProcessReceiver

Returns:

True if this receiver is at a boundary.

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)
         throws NoRoomException

Put a token on the queue contained in this receiver. If the queue is full, then suspend the calling thread (blocking write) and inform the director of the same. Resume the process on detecting room in the queue. If a termination is requested, then initiate the termination of the calling process by throwing a TerminateProcessException. On detecting a room in the queue, put a token in the queue. Check whether any process is blocked on a read from this receiver. If a process is indeed blocked, then unblock the process, and inform the director of the same.

Specified by:

put in interface Receiver

Overrides:

put in class QueueReceiver

Parameters:

token - The token to be put in the receiver, or null to not put anything.

Throws:

NoRoomException - If during initialization, capacity cannot be increased enough to accommodate initial tokens.

reset

public void reset()

Reset the state variables in the receiver.

Specified by:

reset in interface ProcessReceiver

Specified by:

reset in interface Receiver

Overrides:

reset in class AbstractReceiver

requestFinish

public void requestFinish()

Set a flag in the receiver to indicate the onset of termination. This will result in termination of any process that is either blocked on the receiver or is trying to read from or write to it.

Specified by:

requestFinish in interface ProcessReceiver