Package ptolemy.domains.csp.kernel

Class 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$
    Author:
    Neil Smyth, Bilung Lee, Edward A. Lee
    See Also:
    ConditionalBranch, BranchActor, ConditionalReceive, ConditionalSend
    Pt.AcceptedRating:
    Red (bilung)
    Pt.ProposedRating:
    Yellow (eal)

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