Package ptolemy.domains.csp.kernel

Class CSPActor

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, BranchActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    Buffer, Chopstick, ContentionAlarm, Controller, CSPBuffer, CSPGet, CSPMultiSink, CSPMultiSource, CSPPut, CSPSieve, Memory, Philosopher, Processor, ResourcePool
    public class CSPActor
extends TypedAtomicActor
implements BranchActor
    This class is the base class of all atomic actors using the non-deterministic communication and timed features of the communicating sequential processes(CSP) domain.

    Two conditional communication constructs are available: "Conditional if" (CIF) and "Conditional do" (CDO). The constructs are analogous to, but different from, the common if and do statements. The steps involved in using both of these are
    (1) create the branches involved and assign an identification number to each branch.
    (2) call the chooseBranch() method, which invokes the chooseBranch() method of the controller to determine which branch should succeed.
    (3) execute the statements associated with the successful branch.

    Each branch is either an instance of ConditionalSend or ConditionalReceive, depending on the communication in the branch. Please see these classes for details on guarded communication statements, which they represent. The identification number assigned to each branch only needs to identify the branch uniquely for one sequence of the steps above. A good example of how to use a CDO is the code in the actor CSPBuffer, in the ptolemy.domains.csp.lib package. One significant difference between a CDO (or CIF) and a common do (if) is that all the branches are evaluated in parallel, as opposed to sequentially.

    The chooseBranch() method takes an array of the branches as an argument, and simply passes the branches to the chooseBranch() method of the controller to decide which branch is successful. The successful branch is the branch that succeeds with its communication. See the chooseBranch() method of ConditionalBranchController for details about how the successful branch is chosen.

    Time is supported by the method delay(double). This delays the process until time has advanced the argument time from the current model time. If this method is called with a zero argument, then the process continues immediately. As far as each process is concerned, time can only increase while the process is blocked trying to rendezvous or when it is delayed. A process can be aware of the current model time, but it should only affect the model time through delays. Thus time is centralized in that it is advanced by the director controlling the process represented by this actor.

    A process can also choose to delay its execution until the next occasion a deadlock occurs by calling _waitForDeadlock(). The process resumes at the same model time at which it delayed. This is useful if a process wishes to delay itself until some changes to the topology have been carried out.

    The model of computation used in this domain extends the original CSP, as proposed by Hoare in 1978, model of computation in two ways. First it allows non-deterministic communication using both sends and receives. The original model only allowed non-deterministic receives. Second, a centralized notion of time has been added. The original proposal was untimed. Neither of these extensions are new, but it is worth noting the differences between the model used here and the original model. If an actor wishes to use either non-deterministic rendezvous or time, it must derive from this class. Otherwise deriving from AtomicActor is sufficient.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Neil Smyth, Bilung Lee
    See Also:
    ConditionalBranch, ConditionalReceive, ConditionalSend
    Pt.AcceptedRating:
    Yellow (liuj)
    Pt.ProposedRating:
    Green (nsmyth)

    • Constructor Detail

      • CSPActor

        public CSPActor()
        Construct a CSPActor in the default workspace with an empty string as its name. The object is added to the workspace directory. Increment the version number of the workspace.

      • CSPActor

        public CSPActor​(Workspace workspace)
        Construct a CSPActor in the specified workspace with an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. The object is added to the workspace directory. Increment the version number of the workspace.
        Parameters:
        workspace - The workspace that will list the entity.

      • CSPActor

        public CSPActor​(CompositeEntity container,
                java.lang.String name)
         throws IllegalActionException,
                NameDuplicationException
        Construct a CSPActor in the specified container with the specified name. The name must be unique within the container or an exception is thrown. The container argument must not be null, or a NullPointerException will be thrown.
        Parameters:
        container - The TypedCompositeActor that contains this actor.
        name - The actor's name.
        Throws:
        IllegalActionException - If the entity cannot be contained by the proposed container.
        NameDuplicationException - If the name argument coincides with an entity already in the container.

    • Method Detail

      • chooseBranch

        public int chooseBranch​(ConditionalBranch[] branches)
                 throws IllegalActionException
        Determine which branch succeeds with a rendezvous. Pass the branches to ConditionalBranchController to decide.

        Parameters:
        branches - The set of conditional branches involved.
        Returns:
        The ID of the successful branch, or -1 if none of the branches were enabled.
        Throws:
        IllegalActionException - If the rendezvous fails (e.g. because of incompatible types).

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clone this actor into the specified workspace. The new actor is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new actor with the same number of ports (cloned) as the original, but no connections and no container. A container must be set before much can be done with the actor.

        Overrides:
        clone in class TypedAtomicActor
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        A new CSPActor.
        Throws:
        java.lang.CloneNotSupportedException - If cloned ports cannot have as their container the cloned entity (this should not occur), or if one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • delay

        public void delay​(double delta)
           throws IllegalActionException
        Delay this actor. The actor resumes executing when the director advances the current model time to "getCurrentTime() + delta". If the actor tries to delay for a negative time, an exception is thrown. A delay of zero time has no effect and this method returns immediately.
        Parameters:
        delta - The time to delay this actor for from the current time.
        Throws:
        IllegalActionException - If the argument is negative.
        TerminateProcessException - If the director requests termination by calling the protected method _cancelDelay().

      • terminate

        public void terminate()
        Terminate abruptly any threads created by this actor. Note that this method does not allow the threads to terminate gracefully.
        Specified by:
        terminate in interface Executable
        Overrides:
        terminate in class AtomicActor<TypedIOPort>

      • _cancelDelay

        protected void _cancelDelay()
        If the actor is delayed, then cancel the delay. Some time after this method is called, the thread that called delay() will be restarted and the delay() method will throw a TerminateProcessException.

      • _continue

        protected void _continue()
        Resume a delayed actor. This method is only called by CSPDirector after time has sufficiently advanced.

      • _waitForDeadlock

        protected void _waitForDeadlock()
        Wait for deadlock to occur. The current model time will not advance while this actor is delayed. This method may be useful if an actor wishes to delay itself until some topology changes have been carried out.