ptolemy.domains.csp.kernel
Class ConditionalBranchController

java.lang.Object
  ptolemy.domains.csp.kernel.AbstractBranchController
      ptolemy.domains.csp.kernel.ConditionalBranchController

All Implemented Interfaces:

Debuggable

public class ConditionalBranchController
extends AbstractBranchController

A controller that manages the conditional branches for performing conditional communication within CSP (Communication Sequential Processes) domain. Any CSP actors (either atomic or composite) that need the functionality of conditional communication must contain and instantiate an object of this class. In addition, they also needs to implement the interface BranchActor.

The conditional branches are supposed to be created within the parent actor that contains this controller.

The chooseBranch() method takes those branches (an array) as an argument, and controls which branch is successful. The successful branch is the branch that succeeds with its communication. To determine which branch is successful, the guards of all branches are checked. If the guard for a branch is true then that branch is enabled. If no branches are enabled, i.e. if all the guards are false, then -1 is returned to indicate this. If exactly one branch is enabled, the corresponding communication is carried out and the identification number of the branch is returned. If more than one branch is enabled, a separate thread is created and started for each enabled branch. The method then waits for one of the branches to succeed, after which it wakes up and terminates the remaining branches. When the last conditional branch thread has finished, the method returns allowing the parent actor thread to continue.

Since:

Ptolemy II 0.4

Version:

$Id: ConditionalBranchController.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Neil Smyth, Bilung Lee, Edward A. Lee

See Also:

ConditionalBranch, BranchActor, ConditionalReceive, ConditionalSend

Accepted Rating:

Red (bilung)

Proposed Rating:

Yellow (eal)

Field Summary

private java.lang.Thread	_blockedController The thread running chooseBranch if it is blocked.
private int	_branchTrying The ID of the branch currently trying to rendezvous.
private int	_successfulBranch The ID of the branch that has successfully completed a rendezvous.

Fields inherited from class ptolemy.domains.csp.kernel.AbstractBranchController

_branches, _branchesActive, _debugging, _threadList

Constructor Summary

ConditionalBranchController(Actor container)
Construct a controller in the specified container, which should be an actor.

Method Summary

protected void	_branchFailed(int branchNumber) Register the calling branch as failed.
protected void	_branchNotReady(int branchNumber) Release the status of the calling branch as the first branch to be ready to rendezvous.
protected void	_branchSucceeded(int branchID) Registers the calling branch as the successful branch.
protected boolean	_isBranchReady(int branchNumber) Called by ConditionalSend and ConditionalReceive to check whether the calling branch is the first branch to be ready to rendezvous.
private void	_resetConditionalState()
int	chooseBranch(ConditionalBranch[] branches) Determine which branch succeeds with a rendezvous.

Methods inherited from class ptolemy.domains.csp.kernel.AbstractBranchController

_branchBlocked, _branchUnblocked, _debug, _getDirector, addDebugListener, getParent, removeDebugListener, terminate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_branchTrying

private int _branchTrying

The ID of the branch currently trying to rendezvous. It is -1 if no branch is currently trying.

_successfulBranch

private int _successfulBranch

The ID of the branch that has successfully completed a rendezvous.

_blockedController

private java.lang.Thread _blockedController

The thread running chooseBranch if it is blocked.

Constructor Detail

ConditionalBranchController

public ConditionalBranchController(Actor container)

Construct a controller in the specified container, which should be an actor.

Parameters:

container - The parent actor that contains this object.

Method Detail

chooseBranch

public int chooseBranch(ConditionalBranch[] branches)
                 throws IllegalActionException

Determine which branch succeeds with a rendezvous. This method is central to nondeterministic rendezvous. It is given an array of branches, each element of which represents one of the conditional rendezvous branches. If the guard for the branch is false, then the branch is not enabled. It returns the ID of the successful branch, or -1 if none of the branches is enabled.

If exactly one branch is enabled, then the communication is performed directly and the id of the enabled branch is returned. If more than one branch is enabled, a thread is created and started for each enabled branch. These threads try to rendezvous until one succeeds. After a thread succeeds the other threads are killed, and the id of the successful branch is returned.

Parameters:

branches - The set of conditional branches involved.

Returns:

The ID of the successful branch, or -1 if none of the branches is enabled.

Throws:

IllegalActionException - If the rendezvous fails (e.g. because of incompatible types).

_branchFailed

protected void _branchFailed(int branchNumber)

Register the calling branch as failed. This reduces the count of active branches, and if all the active branches have finished, it notifies the internal lock so any threads that are blocked on it can continue. This is called by a conditional branch just before it dies.

Overrides:

_branchFailed in class AbstractBranchController

Parameters:

branchNumber - The ID assigned to the calling branch upon creation.

_branchNotReady

protected void _branchNotReady(int branchNumber)

Release the status of the calling branch as the first branch to be ready to rendezvous. This method is only called when both sides of a communication at a receiver are conditional. In this case, both of the branches have to be the first branches, for their respective actors, for the rendezvous to go ahead. If one branch registers as being first, for its actor, but the other branch cannot, then the status of the first branch needs to be released to allow other branches the possibility of succeeding.

Specified by:

_branchNotReady in class AbstractBranchController

Parameters:

branchNumber - The ID assigned to the branch upon creation.

_branchSucceeded

protected void _branchSucceeded(int branchID)

Registers the calling branch as the successful branch. It reduces the count of active branches, and notifies chooseBranch() that a branch has succeeded. The chooseBranch() method then proceeds to terminate the remaining branches. It is called by the first branch that succeeds with a rendezvous.

Overrides:

_branchSucceeded in class AbstractBranchController

Parameters:

branchID - The ID assigned to the calling branch upon creation.

_isBranchReady

protected boolean _isBranchReady(int branchNumber)

Called by ConditionalSend and ConditionalReceive to check whether the calling branch is the first branch to be ready to rendezvous. If it is, this method sets a private variable to its branch ID so that subsequent calls to this method by other branches know that they are not first.

Specified by:

_isBranchReady in class AbstractBranchController

Parameters:

branchNumber - The ID assigned to the calling branch upon creation.

Returns:

True if the calling branch is the first branch to try to rendezvous, otherwise false.

_resetConditionalState

private void _resetConditionalState()