Package ptolemy.actor.util

Class CausalityInterfaceForComposites

  • All Implemented Interfaces:
    CausalityInterface
    Direct Known Subclasses:
    FSMCausalityInterface, MirrorCausalityInterface, TDLCausalityInterface
    public class CausalityInterfaceForComposites
extends DefaultCausalityInterface
    This class elaborates its base class by providing an algorithm for inferring the causality interface of a composite actor from the causality interfaces of its component actors and their interconnection topology.
    Since:
    Ptolemy II 8.0
    Version:
    $Id$
    Author:
    Edward A. Lee
    Pt.AcceptedRating:
    Red (eal)
    Pt.ProposedRating:
    Yellow (eal)

    • Field Detail

      • _actorDepthVersion

        protected long _actorDepthVersion
        Workspace version when actor depth was last computed.

      • _actorToDepth

        protected java.util.Map<Actor,​java.lang.Integer> _actorToDepth
        A table giving the depths of actors.

      • _dependencyVersion

        protected long _dependencyVersion
        The workspace version where the dependency was last updated.

      • _equivalenceClasses

        protected java.util.Map<IOPort,​java.util.Collection<IOPort>> _equivalenceClasses
        Computed equivalence classes of input ports.

      • _forwardDependencies

        protected java.util.Map<IOPort,​java.util.Map<IOPort,​Dependency>> _forwardDependencies
        Computed dependencies between input ports and output ports of the associated actor.

      • _reverseDependencies

        protected java.util.Map<IOPort,​java.util.Map<IOPort,​Dependency>> _reverseDependencies
        Computed reverse dependencies (the key is now an output port).

    • Constructor Detail

      • CausalityInterfaceForComposites

        public CausalityInterfaceForComposites​(Actor actor,
                                       Dependency defaultDependency)
                                throws java.lang.IllegalArgumentException
        Construct a causality interface for the specified actor.
        Parameters:
        actor - The actor for which this is a causality interface. This is required to be an instance of CompositeEntity.
        defaultDependency - The default dependency of an output port on an input port.
        Throws:
        java.lang.IllegalArgumentException - If the actor parameter is not an instance of CompositeEntity.

    • Method Detail

      • checkForCycles

        public void checkForCycles()
                    throws IllegalActionException
        Check the associated composite actor for causality cycles. If a cycle is found, throw an exception. This method has as a side effect computing the depths of actors and ports within the composite, so subsequent queries for those depths will be low cost.
        Throws:
        IllegalActionException - If a cycle is found.

      • dependentPorts

        public java.util.Collection<IOPort> dependentPorts​(IOPort port)
                                            throws IllegalActionException
        Return a collection of the ports in the associated 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 class presumes (but does not check) that the argument is a port contained by the associated actor. 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.

        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
        Overrides:
        dependentPorts in class DefaultCausalityInterface
        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 set of the input ports in this actor that are in an equivalence class with the specified input. The returned result includes the specified input port.

        An equivalence class is defined as follows. If input ports X and Y each have a dependency equal to oTimesIdentity() on any common port or on two equivalent ports or on 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. Moreover, if the actor has any instance of ParameterPort among its input ports, then all input ports are in an equivalence class. Otherwise, they are not in the same equivalence class. In this base class, we assume the actor has no state and return the equivalence classes determined only by the common dependence of output ports.

        Specified by:
        equivalentPorts in interface CausalityInterface
        Overrides:
        equivalentPorts in class DefaultCausalityInterface
        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:
        IllegalActionException - If the argument is not contained by the associated actor.

      • getDependency

        public Dependency getDependency​(IOPort input,
                                IOPort output)
                         throws IllegalActionException
        Return the dependency between the specified input port and the specified output port. This is done by traversing the network of actors from the input ports. For each output port reachable from an input port, its dependency on the input port is determined by composing the dependencies along all paths from the input port to the output port using oPlus() and oTimes() operators of the dependencies. For any output port that is not reachable from an input port, the dependency on that input port is set to the oPlusIdentity() of the default dependency given in the constructor.

        When called for the first time since a change in the model structure, this method performs the complete analysis of the graph and caches the result. Subsequent calls just look up the result. Note that the complete analysis can be quite expensive. For each input port, it traverses the graph to find all ports reachable from that input port, and tracks the dependencies. In the worst case, the complexity can be N*M^2, where N is the number of input ports and M is the total number of ports in the composite (including the ports of all contained actors). The algorithm used, however, is optimized for typical Ptolemy II models, so in most cases the algorithm completes in time on the order of N*D, where D is the length of the longest chain of ports from an input port to an output port.

        Specified by:
        getDependency in interface CausalityInterface
        Overrides:
        getDependency in class DefaultCausalityInterface
        Parameters:
        input - The input port.
        output - The output port, or null to update the dependencies (and record equivalence classes) without requiring there to be an output port.
        Returns:
        The dependency between the specified input port and the specified output port, or null if a null output is port specified.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • getDepthOfActor

        public int getDepthOfActor​(Actor actor)
                    throws IllegalActionException
        Return the depth of an actor contained (deeply) by the associated composite actor. The depth of an actor is the minimum depth of the output ports. If there are no output ports, then the depth of the actor is the maximum depth of the input ports. If there are no input ports or output ports, the depth is zero.
        Parameters:
        actor - An actor whose depth is requested.
        Returns:
        An integer indicating the depth of the given actor.
        Throws:
        IllegalActionException - If the actor is not within the associated actor.
        See Also:
        getDepthOfPort(IOPort)

      • getDepthOfPort

        public int getDepthOfPort​(IOPort ioPort)
                   throws IllegalActionException
        Return the depth of a port of the associated actor or an actor contained by it. The depth of an output port is the maximum of the depth of all the input ports it directly depends on, or zero if there are no such input ports. The depth of an input port is maximum of the "source depths" of all the input ports in the same equivalence class with the specified port. The "source depth" of an input port is one plus the maximum depth of all output ports that directly source data to it, or zero if there are no such ports.
        Parameters:
        ioPort - A port whose depth is requested.
        Returns:
        An integer representing the depth of the specified ioPort.
        Throws:
        IllegalActionException - If the ioPort does not have a depth (this should not occur if the ioPort is under the control of this director).
        See Also:
        getDepthOfActor(Actor)

      • invalidate

        public void invalidate()
        Indicate that the cached causality information is invalid.

      • topologicalSort

        public java.util.List<Actor> topologicalSort()
                                      throws IllegalActionException
        Return a list of the actors deeply contained within the associated composite actor sorted by actor depth. For actors that have the same depth, the ordering is the order returned by CompositeEntity.deepEntityList(). This method always creates a new list.
        Returns:
        A sorted list of actors.
        Throws:
        IllegalActionException - If a cycle is found.

      • _computeActorDepth

        protected void _computeActorDepth()
                           throws IllegalActionException
        Compute the depth of ports and actors. The actor depth is typically used to prioritize firings in response to pure events (fireAt() calls). The port depth is used to prioritize firings due to input events. Lower depths translate into higher priorities, with the lowest value being zero. The depth of an actor is the minimum depth of the output ports. This typically causes the actor to fire as early as possible to produce an output on those output ports in response to a pure event, but no earlier than the firings of actors that may source it data that the firing may depend on. If there are no output ports, then the depth of the actor it is the maximum depth of the input ports. This typically delays the response to fireAt() until all input events with the same tag have arrived. If there are no input ports or output ports, the depth is zero.
        Throws:
        IllegalActionException - If a zero-delay loop is found.