ptolemy.domains.pn.kernel
Class PNQueueReceiver

java.lang.Object
  extended byptolemy.actor.AbstractReceiver
      extended byptolemy.actor.QueueReceiver
          extended byptolemy.domains.pn.kernel.PNQueueReceiver
All Implemented Interfaces:
ProcessReceiver, Receiver

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.

Since:
Ptolemy II 0.2
Version:
$Id: PNQueueReceiver.java,v 1.88 2004/04/13 03:34:07 cxh Exp $
Author:
Mudit Goel, John S. Davis II
See Also:
QueueReceiver, QueueReceiver
Accepted Rating:
Green (davisj)
Proposed Rating:
Green (mudit)

Field Summary
 
Fields inherited from class ptolemy.actor.QueueReceiver
_queue, INFINITE_CAPACITY
 
Constructor Summary
PNQueueReceiver()
          Construct an empty receiver with no container
PNQueueReceiver(IOPort container)
          Construct an empty receiver with the specified container.
 
Method Summary
 Token get()
          Get a token from this receiver.
 Token get(Branch branch)
          Remove and return the oldest token from the FIFO queue contained in the receiver.
 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()
          This class serves as an example of a ConsumerReceiver and hence this method returns true;
 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()
          This class serves as an example of a ProducerReceiver and hence this method returns true;
 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 prepareToBlock(Branch branch)
          Prepare to register a block.
 void put(Token token)
          Put a token on the queue contained in this receiver.
 void put(Token token, Branch branch)
          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 setReadPending(boolean readPending)
          Set a state flag indicating that there is a process blocked while trying to read from this receiver.
 void setWritePending(boolean writePending)
          Set a state flag indicating that there is a process blocked (write-blocked) while trying to write to the 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.QueueReceiver
clear, elementList, elements, get, getCapacity, getHistoryCapacity, historyElementList, historyElements, historySize, setCapacity, setHistoryCapacity, size
 
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, isKnown, putArray, setContainer
 

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

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.

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.


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 QueueReceiver
Returns:
The token contained by this receiver.

get

public Token get(Branch branch)
Remove and return the oldest token from the FIFO queue contained in the receiver. Terminate the calling process by throwing a TerminateProcessException if requested. Otherwise, if the FIFO queue is empty, then suspend the calling process and inform the director of the same. If a new token becomes available to the FIFO queue, then resume the suspended process. If the queue was not empty, or on availability of a new token (calling process was suspended), take the oldest token from the FIFO queue. Check if any process is blocked on a write to this receiver. If a process is indeed blocked, then unblock the process, and inform the director of the same. Otherwise return.

Specified by:
get in interface ProcessReceiver
Returns:
The oldest Token read from the queue

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 to put into the queue.
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 to get from the queue.
Returns:
True.

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.

This method is not synchronized so the caller

Specified by:
isConnectedToBoundary in interface ProcessReceiver
Returns:
True if this receiver is connected to 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.

This method is not synchronized so the caller

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

This method is not synchronized so the caller

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()
This class serves as an example of a ConsumerReceiver and hence this method returns true;

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()
This class serves as an example of a ProducerReceiver and hence this method returns true;

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 on the queue contained in this receiver. If the queue is full, then suspend the calling process (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.

put

public void put(Token token,
                Branch branch)
Put a token on the queue contained in this receiver. If the queue is full, then suspend the calling process (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 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 ProcessReceiver
Parameters:
token - The token to be put in the receiver.

reset

public void reset()
Reset the state variables in the receiver.

Specified by:
reset in interface ProcessReceiver

setReadPending

public void setReadPending(boolean readPending)
Set a state flag indicating that there is a process blocked while trying to read from this receiver.

Parameters:
readPending - true if the calling process is blocking on a read, false otherwise.

setWritePending

public void setWritePending(boolean writePending)
Set a state flag indicating that there is a process blocked (write-blocked) while trying to write to the receiver.

Parameters:
writePending - true if the calling process is blocking on a write, false otherwise.

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