ptolemy.domains.csp.kernel
Class ConditionalReceive

java.lang.Object
  extended byptolemy.domains.csp.kernel.ConditionalBranch
      extended byptolemy.domains.csp.kernel.ConditionalReceive
All Implemented Interfaces:
java.lang.Runnable

public class ConditionalReceive
extends ConditionalBranch
implements java.lang.Runnable

Represents a guarded communication statement in which the communication is a get(). Thus it represents

guard; get() => statements

It is one branch of either a CDO or a CIF conditional communication construct.

The branches used in a conditional communication construct are controlled by the chooseBranch() method of ConditionalBranchController.

Each branch is created to perform one communication. If more than one branch is enabled (the guard is true or absent), then a thread is created for each enabled branch to try and perform the appropriate rendezvous. If the branch succeeds and is allowed to rendezvous, then it registers itself with the controller and the thread it is running in dies. Otherwise it continues to try and rendezvous until it succeeds or it is notified that another branch has succeeded in with its rendezvous, in which case this branch has failed and the thread it is running in dies.

For rendezvous, the receiver is the key synchronization point. The receiver with which this branch will try to rendezvous is set upon instantiation. It is determined from the port and channel which is passed in in the constructor.

The algorithm by which a branch determines whether or not it has succeeded with its rendezvous is executed in the run method. There are roughly three parts to the algorithm, each of which is relevant to the different rendezvous scenarios.
Case 1: Realized by _arriveAfterPut(). There is a put already waiting at the rendezvous point. In this case the branch attempts to register itself, with the controller, as the first branch ready to rendezvous. If it succeeds, it performs the rendezvous, notifies the controller that it succeeded and returns. If it is not the first, it keeps on trying to register itself until it finally succeeds or another branch successfully rendezvoused in which case it fails and terminates. Note that a put cannot "go away" so it remains in an inner-loop trying to rendezvous or failing.
Case 2: Realized by _arriveAfterConditionalSend(). There is a conditional send waiting. In this case it tries to register both branches with their controllers as the first to try. If it succeeds it performs the transfer, notifies the controller and returns. It performs the registration in two steps, first registering this branch and then registering the other branch. If it successfully registers this branch, but cannot register the other, it unregisters itself as the first branch trying, and starts trying to rendezvous from the beginning. This is because the conditional send could "go away". If it is unable to register itself as the first branch to try, it again starts trying to rendezvous from the beginning.
Case 3: Realized by _arriveFirst(). If there is neither a put or a conditional send waiting, it sets a flag in the receiver that a conditional receive is trying to rendezvous. It then waits until a put is executed on the receiver, or until another branch succeeds and this branch fails. If this branch fails, it resets the flag in the receiver, notifies the controller and returns. Note that it only needs to wait on a put as if a conditional send is executed on the receiver, it is the branch which is responsible for checking that the rendezvous can proceed. Thus, in the case where two conditional branches are trying to rendezvous at a receiver, it is the responsibility of the branch arriving second to check that the rendezvous can proceed(see case 2).

Since:
Ptolemy II 0.2
Version:
$Id: ConditionalReceive.java,v 1.68 2004/04/13 03:25:07 cxh Exp $
Author:
Neil Smyth
See Also:
ConditionalBranch
Accepted Rating:
Green (kienhuis)

Proposed Rating:
Green (nsmyth)

Field Summary
 
Fields inherited from class ptolemy.domains.csp.kernel.ConditionalBranch
_guard
 
Constructor Summary
ConditionalReceive(boolean guard, IOPort port, int channel, int branch)
          Create a guarded communication with a get() communication.
ConditionalReceive(boolean guard, IOPort port, int channel, int branch, ConditionalBranchController cbc)
          Create a guarded communication with a get() communication.
 
Method Summary
protected  boolean _arriveAfterConditionalSend(CSPReceiver receiver, ConditionalBranchController controller)
          Encounter a conditionalSend that is already waiting on this conditionalReceive.
protected  void _arriveAfterPut(CSPReceiver receiver, ConditionalBranchController controller)
          Encounter a non-conditional put that is already waiting on this conditionalReceive.
protected  void _arriveFirst(CSPReceiver receiver, ConditionalBranchController controller)
          Begin a rendezvous attempt prior to any other conditionalSends or (non-conditional) put attempts.
 void run()
          The run method has roughly three parts: (1) where there is already a put waiting, (2) where there is a ConditionalSend waiting, and (3) where the ConditionalReceive is the first to arrive at the receiver.
 
Methods inherited from class ptolemy.domains.csp.kernel.ConditionalBranch
getController, getGuard, getID, getReceiver, getToken, isAlive
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ConditionalReceive

public ConditionalReceive(boolean guard,
                          IOPort port,
                          int channel,
                          int branch)
                   throws IllegalActionException
Create a guarded communication with a get() communication.

Parameters:
guard - The guard for the guarded communication statement represented by this object.
port - The IOPort containing the channel (and thus receiver) that this branch will try to rendezvous with.
channel - The channel in the IOPort that this branch is trying to rendezvous with.
branch - The identification number assigned to this branch upon creation by the CSPActor.
Throws:
IllegalActionException - If the channel has more than one receiver or if the receiver is not of type CSPReceiver.

ConditionalReceive

public ConditionalReceive(boolean guard,
                          IOPort port,
                          int channel,
                          int branch,
                          ConditionalBranchController cbc)
                   throws IllegalActionException
Create a guarded communication with a get() communication. This constructor allows actors which are not CSPActors access to CSP functionality by providing their own ConditionalBranchController.

Parameters:
guard - The guard for the guarded communication statement represented by this object.
port - The IOPort containing the channel (and thus receiver) that this branch will try to rendezvous with.
channel - The channel in the IOPort that this branch is trying to rendezvous with.
branch - The identification number assigned to this branch upon creation by the CSPActor.
cbc - The ConditionalBranchController that this branch uses.
Throws:
IllegalActionException - If the channel has more than one receiver or if the receiver is not of type CSPReceiver.
Method Detail

run

public void run()
The run method has roughly three parts: (1) where there is already a put waiting, (2) where there is a ConditionalSend waiting, and (3) where the ConditionalReceive is the first to arrive at the receiver.

The algorithm used in this method, together with some methods in ConditionalBranchController, control how conditional communication takes place in the CSP domain.

Specified by:
run in interface java.lang.Runnable

_arriveAfterConditionalSend

protected boolean _arriveAfterConditionalSend(CSPReceiver receiver,
                                              ConditionalBranchController controller)
                                       throws java.lang.InterruptedException
Encounter a conditionalSend that is already waiting on this conditionalReceive. Since this conditionalReceive arrived second, check if both branches are "first" and if so perform the data transfer and reset the state of the receiver. Since a conditionalSend can "disappear," then this method can return to the top of the main loop in the run method that calls this method. Return true if this method should go to the top of the calling loop; return false otherwise.

Parameters:
controller - The conditional branch controller that control this conditional receive.
receiver - The CSPReceiver through which a rendezvous attempt is taking place.
Returns:
true if this method should continue at the beginning of the loop that calls this method; otherwise return false.
Throws:
java.lang.InterruptedException

_arriveAfterPut

protected void _arriveAfterPut(CSPReceiver receiver,
                               ConditionalBranchController controller)
                        throws java.lang.InterruptedException
Encounter a non-conditional put that is already waiting on this conditionalReceive. Since a non-conditional put can not disappear, wait (via a while loop) until it successfully rendezvouses or dies.

Parameters:
controller - The conditional branch that control this conditional receive.
receiver - The CSPReceiver through which a rendezvous attempt is taking place.
Throws:
java.lang.InterruptedException

_arriveFirst

protected void _arriveFirst(CSPReceiver receiver,
                            ConditionalBranchController controller)
                     throws java.lang.InterruptedException
Begin a rendezvous attempt prior to any other conditionalSends or (non-conditional) put attempts. Wait until a put or conditionalSend attempt is made by another branch.

Parameters:
controller - The conditional branch controller that control this conditional receive.
receiver - The CSPReceiver through which a rendezvous attempt is taking place.
Throws:
java.lang.InterruptedException