ptolemy.domains.csp.kernel
Class CSPReceiver

java.lang.Object
  extended byptolemy.actor.AbstractReceiver
      extended byptolemy.domains.csp.kernel.CSPReceiver
All Implemented Interfaces:
ProcessReceiver, Receiver

public class CSPReceiver
extends AbstractReceiver
implements ProcessReceiver

Receiver for CSP style communication. In CSP all communication is via synchronous message passing, so both the the sending and receiving process need to rendezvous at the receiver. For rendezvous, the receiver is the key synchronization point. It is assumed each receiver has at most one thread trying to send to it and at most one thread trying to receive from it at any one time. The receiver performs the synchronization necessary for simple rendezvous (get() and put() operations). It also stores the flags that allow the ConditionalSend and ConditionalReceive branches to know when they can proceed.

Since:
Ptolemy II 0.2
Version:
$Id: CSPReceiver.java,v 1.80 2004/04/13 03:24:59 cxh Exp $
Author:
Neil Smyth, John S. Davis II
Accepted Rating:
Green (kienhuis)
Proposed Rating:
Green (nsmyth)

Constructor Summary
CSPReceiver()
          Construct a CSPReceiver with no container.
CSPReceiver(IOPort container)
          Construct a CSPReceiver with the specified container.
 
Method Summary
protected  void _checkFlagsAndWait()
          This method wraps the wait() call between checks on the state of the receiver.
protected  ConditionalBranchController _getOtherController()
          The controller of the conditional branch to reach the rendezvous point first.
protected  boolean _isConditionalReceiveWaiting()
          Flag indicating whether or not a ConditionalReceive is trying to rendezvous with this receiver.
protected  boolean _isConditionalSendWaiting()
          Flag indicating whether or not a ConditionalSend is trying to rendezvous with this receiver.
protected  boolean _isGetWaiting()
          Flag indicating whether or not a get() is waiting to rendezvous at this receiver.
protected  boolean _isPutWaiting()
          Flag indicating whether or not a put() is waiting to rendezvous at this receiver.
protected  void _setConditionalReceive(boolean v, ConditionalBranchController p, int otherID)
          Set a flag so that a ConditionalSend branch knows whether or not a ConditionalReceive is ready to rendezvous with it.
protected  void _setConditionalSend(boolean v, ConditionalBranchController p, int otherID)
          Set a flag so that a ConditionalReceive branch knows whether or not a ConditionalSend is ready to rendezvous with it.
 void clear()
          Reset local flags.
 Token get()
          Get a token from the mailbox receiver and specify a null Branch to control the execution of this method.
 Token get(Branch branch)
          Retrieve a Token from the receiver by rendezvous.
protected  int getOtherID()
           
 boolean hasRoom()
          Return true.
 boolean hasRoom(int tokens)
          Return true.
 boolean hasToken()
          Return true.
 boolean hasToken(int tokens)
          Return true.
 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 markBlocked(Branch branch)
          If this receiver is involved in a branch, then mark the receiver blocked; otherwise mark the actor blocked.
 void markUnblocked()
          If this receiver is involved in a branch, then mark the receiver unblocked; otherwise mark the actor unblocked.
 void put(Token token)
          Put a token into the mailbox receiver and specify a null Branch to control the execution of this method.
 void put(Token t, Branch branch)
          Place a Token into the receiver via rendezvous.
 void requestFinish()
          The model has finished executing, so set a flag so that the next time an actor tries to get or put it gets a TerminateProcessException which will cause it to finish.
 void reset()
          Reset local flags.
 
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
getArray, getContainer, isKnown, putArray, setContainer
 

Constructor Detail

CSPReceiver

public CSPReceiver()
Construct a CSPReceiver with no container.


CSPReceiver

public CSPReceiver(IOPort container)
            throws IllegalActionException
Construct a CSPReceiver with the specified container.

Parameters:
container - The port containing this receiver.
Throws:
IllegalActionException - If this receiver cannot be contained by the proposed container.
Method Detail

clear

public void clear()
Reset local flags. FIXME

Specified by:
clear in interface Receiver
Overrides:
clear in class AbstractReceiver

get

public Token get()
Get a token from the mailbox receiver and specify a null Branch to control the execution of this method.

Specified by:
get in interface Receiver
Specified by:
get in class AbstractReceiver
Returns:
The token contained by this receiver.

get

public Token get(Branch branch)
Retrieve a Token from the receiver by rendezvous. This method does not return until the rendezvous has been completed. If a put has already been reached, it notifies the waiting put and waits for the rendezvous to complete. When the rendezvous is complete it returns with the token. If a put has not yet been reached, the method delays until a put is reached. It is assumed that at most one process is trying to receive from and send to the channel associated with this receiver.

Specified by:
get in interface ProcessReceiver
Returns:
The token transferred by the rendezvous.
Throws:
TerminateProcessException - If execution termination has been requested, or if the execution is abruptly terminated from the outside (via an InterruptedException).

hasRoom

public boolean hasRoom()
Return true. This method returns true in all cases to indicate that the next call to put() will succeed without throwing a NoRoomException, as indeed it will, even if not right away. Note that if this were to return true only if a rendezvous was pending, then polymorphic actors would busy wait.

Specified by:
hasRoom in interface Receiver
Specified by:
hasRoom in class AbstractReceiver
Returns:
True.

hasRoom

public boolean hasRoom(int tokens)
Return true. This method returns true in all cases to indicate that any number of calls to put() will succeed without throwing a NoRoomException, as indeed they will, even if not right away. Note that if this were to return true only if a rendezvous was pending, then polymorphic actors would busy wait.

Specified by:
hasRoom in interface Receiver
Specified by:
hasRoom in class AbstractReceiver
Parameters:
tokens - The number of tokens to put into this receiver.
Returns:
True.

hasToken

public boolean hasToken()
Return true. This method returns true in all cases to indicate that the next call to get() will succeed without throwing a NoTokenException, as indeed it will, even if not right away. Note that if this were to return true only if a rendezvous was pending, then polymorphic actors would busy wait.

Specified by:
hasToken in interface Receiver
Specified by:
hasToken in class AbstractReceiver
Returns:
True.

hasToken

public boolean hasToken(int tokens)
Return true. This method returns true in all cases to indicate that any number of calls to get() will succeed without throwing a NoTokenException, as indeed they will, even if not right away. Note that if this were to return true only if a rendezvous was pending, then polymorphic actors would busy wait.

Specified by:
hasToken in interface Receiver
Specified by:
hasToken in class AbstractReceiver
Parameters:
tokens - The number of tokens desired.
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 should be.

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.

markBlocked

public void markBlocked(Branch branch)
If this receiver is involved in a branch, then mark the receiver blocked; otherwise mark the actor blocked.


markUnblocked

public void markUnblocked()
If this receiver is involved in a branch, then mark the receiver unblocked; otherwise mark the actor unblocked.


put

public void put(Token token)
Put a token into the mailbox receiver and specify a null Branch to control the execution of this method.

Specified by:
put in interface Receiver
Specified by:
put in class AbstractReceiver
Parameters:
token - The token to put into the receiver.

put

public void put(Token t,
                Branch branch)
Place a Token into the receiver via rendezvous. This method does not return until the rendezvous has been completed. If get has already been reached, it notifies the waiting get and waits for the rendezvous to complete. When the rendezvous is complete it returns. If a get has not yet been reached, the method delays until a get is reached. It is assumed that at most one process is trying to receive from and send to the channel associated with this receiver. to receive from it and at most one channel send to it.

Specified by:
put in interface ProcessReceiver
Parameters:
t - The token being transferred in the rendezvous.
Throws:
TerminateProcessException - If execution termination has been requested, or if the execution is abruptly terminated from the outside (via an InterruptedException).

requestFinish

public void requestFinish()
The model has finished executing, so set a flag so that the next time an actor tries to get or put it gets a TerminateProcessException which will cause it to finish.

Specified by:
requestFinish in interface ProcessReceiver

reset

public void reset()
Reset local flags.

Specified by:
reset in interface ProcessReceiver

_checkFlagsAndWait

protected void _checkFlagsAndWait()
                           throws TerminateProcessException,
                                  java.lang.InterruptedException
This method wraps the wait() call between checks on the state of the receiver. The flags checked are whether the receiver has been finished. The actions taken depending on the flags apply to whatever process this method was invoked from. Note: It should only be called from CSPReceiver and conditional rendezvous branches, and then only from code that already has the lock on this receiver.

Throws:
TerminateProcessException - If the actor to which this receiver belongs has been terminated while still running i.e it was not allowed to run to completion.
java.lang.InterruptedException - If the actor is interrupted while waiting(for a rendezvous to complete).

_getOtherController

protected ConditionalBranchController _getOtherController()
The controller of the conditional branch to reach the rendezvous point first. For a rendezvous to occur when both communications at the receiver are from conditional branches, then the rendezvous can only proceed if both the branches are the first branches to be ready to succeed for their respective controllers. This is checked by the second branch to arrive at the rendezvous point, for which it requires the actor that created the other branch. Thus the first branch to arrive stores its controller in the receiver when it is setting the appropriate flag, which is what is returned by this method.

Returns:
The controller which controls the first conditional branch to arrive.

getOtherID

protected int getOtherID()

_isConditionalReceiveWaiting

protected boolean _isConditionalReceiveWaiting()
Flag indicating whether or not a ConditionalReceive is trying to rendezvous with this receiver.

Returns:
True if a ConditionalReceive branch is trying to rendezvous with this receiver.

_isConditionalSendWaiting

protected boolean _isConditionalSendWaiting()
Flag indicating whether or not a ConditionalSend is trying to rendezvous with this receiver.

Returns:
True if a ConditionalSend branch is trying to rendezvous with this receiver.

_isGetWaiting

protected boolean _isGetWaiting()
Flag indicating whether or not a get() is waiting to rendezvous at this receiver.

Returns:
True if a get() is waiting to rendezvous.

_isPutWaiting

protected boolean _isPutWaiting()
Flag indicating whether or not a put() is waiting to rendezvous at this receiver.

Returns:
True if a put() is waiting to rendezvous.

_setConditionalSend

protected void _setConditionalSend(boolean v,
                                   ConditionalBranchController p,
                                   int otherID)
Set a flag so that a ConditionalReceive branch knows whether or not a ConditionalSend is ready to rendezvous with it.

Parameters:
v - Boolean indicating whether or not a conditional send is waiting to rendezvous.
p - The CSPActor which contains the ConditionalSend branch that is trying to rendezvous. It is stored in the receiver so that if a ConditionalReceive arrives, it can easily check whether the ConditionalSend branch was the first branch of its conditional construct(CIF or CDO) to succeed.
otherID - The branch ID of the branch requesting the conditional send.

_setConditionalReceive

protected void _setConditionalReceive(boolean v,
                                      ConditionalBranchController p,
                                      int otherID)
Set a flag so that a ConditionalSend branch knows whether or not a ConditionalReceive is ready to rendezvous with it.

Parameters:
v - Boolean indicating whether or not a conditional receive is waiting to rendezvous.
p - The CSPActor which contains the ConditionalReceive branch that is trying to rendezvous. It is stored in the receiver so that if a ConditionalSend arrives, it can easily check whether the ConditionalReceive branch was the first branch of its conditional construct(CIF or CDO) to succeed.
otherID - The branch ID of the branch requesting the conditional receive.