001/* Interface representing dependencies between ports of an associated actor.
002
003 Copyright (c) 2008-2013 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027 */
028package ptolemy.actor.util;
029
030import java.util.Collection;
031
032import ptolemy.actor.Actor;
033import ptolemy.actor.IOPort;
034import ptolemy.kernel.util.IllegalActionException;
035
036///////////////////////////////////////////////////////////////////
037//// CausalityInterface
038
039/**
040 This interface defines a causality interfaces for actor networks as
041 described in the paper "Causality Interfaces for Actor Networks" by
042 Ye Zhou and Edward A. Lee, ACM Transactions on Embedded Computing
043 Systems (TECS), April 2008, as available as <a
044 href="http://www.eecs.berkeley.edu/Pubs/TechRpts/2006/EECS-2006-148.pdf">
045 Technical Report No. UCB/EECS-2006-148</a>, November 16, 2006.
046 Causality interfaces represent dependencies between input and output
047 ports of an actor and can be used to perform scheduling or static
048 analysis on actor models.  Implementers of this interface must ensure
049 consistency between the methods {@link #dependentPorts(IOPort)},
050 {@link #equivalentPorts(IOPort)}, and {@link #getDependency(IOPort, IOPort)}.
051
052 @see Dependency
053
054 @author Edward A. Lee
055 @version $Id$
056 @since Ptolemy II 8.0
057 @Pt.ProposedRating Yellow (eal)
058 @Pt.AcceptedRating Red (eal)
059 */
060public interface CausalityInterface {
061
062    ///////////////////////////////////////////////////////////////////
063    ////                         public methods                    ////
064
065    /** Set the dependency that the specified output port has
066     *  on the specified input port to represent a time
067     *  delay with the specified value and superdense time index.
068     *  Implementations of this method should be adaptive to the type
069     *  of Dependency provided by the director. For example, if the
070     *  director provides a BooleanDependency, then an implementation
071     *  of this method should define the dependency to be oTimesIdentity if
072     *  the timeDelay is 0.0 and the index is 0, and otherwise it should
073     *  be oPlusIdentity.
074     *  @param input The input port.
075     *  @param output The output port with a time delay dependency on the
076     *   input port.
077     *  @param timeDelay The time delay.
078     *  @param index The superdense time index.
079     */
080    public void declareDelayDependency(IOPort input, IOPort output,
081            double timeDelay, int index);
082
083    /** Return a collection of the ports in this actor that depend on
084     *  or are depended on by the specified port. A port Y depends
085     *  on a port X if Y is an output and X is an input and
086     *  getDependency(X,Y) returns the oTimesIdentity.
087     *  The argument port should be contained by the same actor
088     *  returned by getActor().
089     *  @param port The port to find the dependents of.
090     *  @exception IllegalActionException If the dependency
091     *   cannot be determined.
092     *  @return a collection of ports in this actor that depend
093     *   on or are depended on by the specified port.
094     */
095    public Collection<IOPort> dependentPorts(IOPort port)
096            throws IllegalActionException;
097
098    /** Return a collection of input ports in the associated actor that are
099     *  in the same equivalence class as the specified input port.
100     *  An equivalence class is defined as follows.
101     *  If input ports X and Y each have a dependency equal to the
102     *  default dependency's oTimesIdentity to any common output port
103     *  or to the state of the associated actor, then they
104     *  are in an equivalence class. That is,
105     *  there is a causal dependency. They are also in
106     *  the same equivalence class if there is a port Z
107     *  in an equivalence class with X and in an equivalence
108     *  class with Y. Otherwise, they are not in the same
109     *  equivalence class.
110     *  @param input The port to find the equivalence class of.
111     *  @exception IllegalActionException If the equivalent ports
112     *   cannot be determined.
113     *  @return a collection of input ports that are in the same equivalence
114     *  class as the specified input port.
115     */
116    public Collection<IOPort> equivalentPorts(IOPort input)
117            throws IllegalActionException;
118
119    /** Return the associated actor.
120     *  @return The actor for which this is a dependency.
121     */
122    public Actor getActor();
123
124    /** Return the default dependency.
125     *  @return The default dependency.
126     */
127    public Dependency getDefaultDependency();
128
129    /** Return the dependency between the specified input port
130     *  and the specified output port.
131     *  @param input The specified input port.
132     *  @param output The specified output port.
133     *  @return The dependency between the specified input port
134     *   and the specified output port.
135     *  @exception IllegalActionException If the dependency
136     *   cannot be determined.
137     */
138    public Dependency getDependency(IOPort input, IOPort output)
139            throws IllegalActionException;
140
141    /** Remove the dependency that the specified output port has
142     *  on the specified input port, meaning that the dependency
143     *  is set to oPlusIdentity. If there is no
144     *  defined dependency between the two ports, then this
145     *  method will have no effect.
146     *  @param inputPort The input port.
147     *  @param outputPort The output port that does not depend on the
148     *   input port.
149     */
150    public void removeDependency(IOPort inputPort, IOPort outputPort);
151}