Package ptolemy.actor.util

Class DefaultCausalityInterface

  • All Implemented Interfaces:
    CausalityInterface
    Direct Known Subclasses:
    BreakCausalityInterface, CausalityInterfaceForComposites
    public class DefaultCausalityInterface
extends java.lang.Object
implements CausalityInterface
    This class provides causality interfaces for actor networks as described in the paper "Causality Interfaces for Actor Networks" by Ye Zhou and Edward A. Lee, ACM Transactions on Embedded Computing Systems (TECS), April 2008, as available as Technical Report No. UCB/EECS-2006-148, November 16, 2006. Specifically, this class represents a simple default causality interface where every output port depends on every input port, unless removeDependency(IOPort, IOPort) has been called to prune the dependencies. In the latter case, the dependencies are pruned to not include the ones that were specified in that call.

    In all cases, if there is any PortParameter in the actor, then all input ports become members of the same equivalence class, regardless of what dependencies have been pruned using removeDependency(IOPort, IOPort). The reason for this is that any output, present or future, may depend on the values at such port parameters. In particular, it is necessary for inputs on these port parameters to be present when any other input is processed because it affects the parameters of the actor.

    Causality interfaces represent dependencies between input and output ports of an actor and can be used to perform scheduling or static analysis on actor models.

    Since:
    Ptolemy II 8.0
    Version:
    $Id$
    Author:
    Edward A. Lee
    Pt.AcceptedRating:
    Red (eal)
    Pt.ProposedRating:
    Yellow (eal)

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void _growDependencies​(IOPort input, java.util.Set<IOPort> inputs, java.util.Set<IOPort> outputs)
      If the input port is already in the inputs set, do nothing and return.
      void declareDelayDependency​(IOPort input, IOPort output, double timeDelay, int index)
      Set the dependency that the specified output port has on the specified input port to represent a time delay with the specified value and superdense time index.
      java.util.Collection<IOPort> dependentPorts​(IOPort port)
      Return a collection of the ports in this actor that depend on or are depended on by the specified port.
      java.util.Collection<IOPort> equivalentPorts​(IOPort input)
      Return a collection of the input ports in this actor that are in the same equivalence class with the specified input port.
      Actor getActor()
      Return the actor for which this is a dependency.
      Dependency getDefaultDependency()
      Return the default dependency specified in the constructor.
      Dependency getDependency​(IOPort input, IOPort output)
      Return the dependency between the specified input port and the specified output port.
      void removeDependency​(IOPort inputPort, IOPort outputPort)
      Remove the dependency that the specified output port has on the specified input port.
      java.lang.String toString()
      Return a description of the causality interfaces.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • _actor

        protected Actor _actor
        The associated actor.

      • _backwardPrunedDependencies

        protected java.util.Map<IOPort,​java.util.Set<IOPort>> _backwardPrunedDependencies
        A record of removed dependencies from output to input, if any. In this case, if the dependency between the ports are anything other than the oTimesIdentity, then the dependency is removed.

      • _EMPTY_COLLECTION

        protected static final java.util.Collection<IOPort> _EMPTY_COLLECTION
        Empty collection for use by dependentPort().

      • _defaultDependency

        protected Dependency _defaultDependency
        The default dependency of an output port on an input port.

      • _delayDependencies

        protected java.util.Map<IOPort,​java.util.Map<IOPort,​Dependency>> _delayDependencies
        A record of delay dependencies from input to output, if any.

      • _forwardPrunedDependencies

        protected java.util.Map<IOPort,​java.util.Set<IOPort>> _forwardPrunedDependencies
        A record of removed dependencies from input to output, if any. In this case, if the dependency between the ports are anything other than the oTimesIdentity, then the dependency is removed.

    • Constructor Detail

      • DefaultCausalityInterface

        public DefaultCausalityInterface​(Actor actor,
                                 Dependency defaultDependency)
        Construct a causality interface for the specified actor.
        Parameters:
        actor - The actor for which this is a causality interface.
        defaultDependency - The default dependency of an output port on an input port.

    • Method Detail

      • declareDelayDependency

        public void declareDelayDependency​(IOPort input,
                                   IOPort output,
                                   double timeDelay,
                                   int index)
        Set the dependency that the specified output port has on the specified input port to represent a time delay with the specified value and superdense time index. This method is adaptive to the type of Dependency provided in the constructor. For example, if the constructor provides a BooleanDependency, then this method defines the dependency to be TRUE if the timeDelay is 0.0 and the index is 0, and otherwise it should be FALSE. If the Dependency is a RealDependency, then it uses the timeDelay argument to define the dependency. If it is a SuperdenseDependency, then it uses both the timeDelay and the index.
        Specified by:
        declareDelayDependency in interface CausalityInterface
        Parameters:
        input - The input port.
        output - The output port with a time delay dependency on the input port.
        timeDelay - The time delay.
        index - The superdense time index.

      • dependentPorts

        public java.util.Collection<IOPort> dependentPorts​(IOPort port)
                                            throws IllegalActionException
        Return a collection of the ports in this actor that depend on or are depended on by the specified port. A port X depends on a port Y if X is an output and Y is an input and getDependency(X,Y) returns oTimesIdentity() of the default dependency specified in the constructor.

        This base class presumes (but does not check) that the argument is a port contained by the associated actor. By default, if the actor is an input, then it returns a collection of all the outputs. If the actor is output, then it returns a collection of all the inputs. However, if removeDependency(IOPort, IOPort) has been called, then it prunes the results to not include ports where the dependency has been explicitly removed.

        Derived classes may override this, but they may need to also override getDependency(IOPort, IOPort) and equivalentPorts(IOPort) to be consistent.

        Specified by:
        dependentPorts in interface CausalityInterface
        Parameters:
        port - The port to find the dependents of.
        Returns:
        a collection of ports that depend on or are depended on by the specified port.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • equivalentPorts

        public java.util.Collection<IOPort> equivalentPorts​(IOPort input)
                                             throws IllegalActionException
        Return a collection of the input ports in this actor that are in the same equivalence class with the specified input port. This base class returns a collection of all the input ports of the associated actor, unless removeDependencies() has been called. In the latter case, it constructs the equivalence class based on the remaining dependencies on output ports, unless there is an instance of PortParameter in the actor. In that case, it again returns a collection of all the input ports.

        If derived classes override this, they may also need to override getDependency(IOPort,IOPort) and dependentPorts(IOPort) to be consistent. The returned result should always include the specified input port.

        An equivalence class is defined as follows. If input ports X and Y each have a dependency on any common port or on two equivalent ports, or they each can affect the state of the associated actor, then they are in an equivalence class. That is, there is a causal dependency. They are also in the same equivalence class if there is a port Z in an equivalence class with X and in an equivalence class with Y. If the actor has any instance of ParameterPort, then all input ports are in the same equivalence class. Otherwise, they are not in the same equivalence class.

        Specified by:
        equivalentPorts in interface CausalityInterface
        Parameters:
        input - The port to find the equivalence class of.
        Returns:
        set of the input ports in this actor that are in an equivalence class with the specified input.
        Throws:
        java.lang.IllegalArgumentException - If the argument is not contained by the associated actor.
        IllegalActionException - Not thrown in this base class.

      • getActor

        public Actor getActor()
        Return the actor for which this is a dependency.
        Specified by:
        getActor in interface CausalityInterface
        Returns:
        The actor for which this is a dependency.

      • getDependency

        public Dependency getDependency​(IOPort input,
                                IOPort output)
                         throws IllegalActionException
        Return the dependency between the specified input port and the specified output port. This base class returns the default dependency if the first port is an input port owned by this actor and the second one is an output port owned by this actor. Otherwise, it returns the additive identity of the dependency. Also, if removeDependency(IOPort, IOPort) has been called with the same two specified ports, then this method will return the additive identity.

        Derived classes should override this method to provide actor-specific dependency information. If they do so, then they may also need to override equivalentPorts(IOPort) and dependentPorts(IOPort) to be consistent.

        Specified by:
        getDependency in interface CausalityInterface
        Parameters:
        input - The input port.
        output - The output port.
        Returns:
        The dependency between the specified input port and the specified output port.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • toString

        public java.lang.String toString()
        Return a description of the causality interfaces.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A description of the causality interfaces.

      • removeDependency

        public void removeDependency​(IOPort inputPort,
                             IOPort outputPort)
        Remove the dependency that the specified output port has on the specified input port. Specifically, calling this method ensures that getDependency(inputPort, outputPort) will return defaultDependency.oPlusIdentity() instead of the default defaultDependency.oTimesIdentity(). It also adjusts what is returned by equivalentPorts(IOPort) and dependentPorts(IOPort).
        Specified by:
        removeDependency in interface CausalityInterface
        Parameters:
        inputPort - The input port.
        outputPort - The output port that does not depend on the input port.
        See Also:
        getDependency(IOPort, IOPort)

      • _growDependencies

        protected void _growDependencies​(IOPort input,
                                 java.util.Set<IOPort> inputs,
                                 java.util.Set<IOPort> outputs)
                          throws IllegalActionException
        If the input port is already in the inputs set, do nothing and return. Otherwise, add the input port to the inputs set, and its output dependents to the outputs set. If any of those output dependents were not already in the outputs set, add them, and then recursively invoke this same method on all input ports that depend on those outputs.
        Parameters:
        input - The input port.
        inputs - The set of inputs to which input is added if it is not already present.
        outputs - The set of output dependents to which the output dependents are added if input was not in the inputs set.
        Throws:
        IllegalActionException - Not thrown in this base class.