001/* Measure the time that events at one input have to wait for events at another.
002
003 Copyright (c) 1998-2015 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.domains.de.lib;
029
030import java.util.Vector;
031
032import ptolemy.actor.TypedIOPort;
033import ptolemy.actor.util.Time;
034import ptolemy.data.DoubleToken;
035import ptolemy.data.type.BaseType;
036import ptolemy.domains.de.kernel.DEActor;
037import ptolemy.domains.de.kernel.DEDirector;
038import ptolemy.kernel.CompositeEntity;
039import ptolemy.kernel.util.IllegalActionException;
040import ptolemy.kernel.util.NameDuplicationException;
041import ptolemy.kernel.util.Workspace;
042
043///////////////////////////////////////////////////////////////////
044//// WaitingTime
045
046/**
047 This actor measures the time that events at one input have to wait for
048 events at another.  Specifically, there will be one output event for
049 each <i>waiter</i> input event.  But the output event is delayed until the
050 next arrival of an event at <i>waitee</i>.  When one or more events arrive
051 at <i>waitee</i>, then all events that have arrived at <i>waiter</i> since
052 the last <i>waitee</i> (or since the start of the execution) trigger an
053 output.  The value of each output is the time that the <i>waiter</i> event
054 waited for <i>waitee</i>.  The inputs have undeclared type, so anything
055 is acceptable.  The output is always a DoubleToken.
056
057 @author Lukito Muliadi, Edward A Lee
058 @version $Id$
059 @since Ptolemy II 0.3
060 @Pt.ProposedRating Yellow (eal)
061 @Pt.AcceptedRating Yellow (cxh)
062 */
063public class WaitingTime extends DEActor {
064    /** Construct an actor with the specified container and name.
065     *  @param container The container.
066     *  @param name The name.
067     *
068     *  @exception IllegalActionException If the entity cannot be contained
069     *   by the proposed container.
070     *  @exception NameDuplicationException If the container already has an
071     *   actor with this name.
072     */
073    public WaitingTime(CompositeEntity container, String name)
074            throws NameDuplicationException, IllegalActionException {
075        super(container, name);
076
077        // create the ports
078        output = new TypedIOPort(this, "output", false, true);
079        output.setTypeEquals(BaseType.DOUBLE);
080        waiter = new TypedIOPort(this, "waiter", true, false);
081        waitee = new TypedIOPort(this, "waitee", true, false);
082        _waiting = new Vector();
083    }
084
085    ///////////////////////////////////////////////////////////////////
086    ////                       ports and parameters                ////
087
088    /** The output, which is always a DoubleToken representing the
089     *  that a waiter waited for an input at the <i>waitee</i> input.
090     */
091    public TypedIOPort output;
092
093    /** An input event here waits for the next event at the <i>waitee</i>
094     *  input.  The type of this port is undeclared, so any input is acceptable.
095     */
096    public TypedIOPort waiter;
097
098    /** An input event here triggers an output event for each <i>waiter</i>
099     *  input that arrived since the last input here.  The type of this
100     *  port is undeclared, so any input is acceptable.
101     */
102    public TypedIOPort waitee;
103
104    ///////////////////////////////////////////////////////////////////
105    ////                         public methods                    ////
106
107    /** Clone the actor into the specified workspace. This calls the
108     *  base class and then sets the ports.
109     *  @param workspace The workspace for the new object.
110     *  @return A new actor.
111     *  @exception CloneNotSupportedException If a derived class has
112     *   has an attribute that cannot be cloned.
113     */
114    @Override
115    public Object clone(Workspace workspace) throws CloneNotSupportedException {
116        WaitingTime newObject = (WaitingTime) super.clone(workspace);
117        newObject._waiting = new Vector();
118        return newObject;
119    }
120
121    /** If this firing is triggered by an event at <i>waitee</i>, then output
122     *  the waiting time for each prior event arrival at <i>waiter</i>
123     *  since the last arrival of waitee.  If there is no event at
124     *  <i>waitee</i>, then record the time of arrival of the events
125     *  at <i>waiter</i>, and produce no output.
126     *  @exception IllegalActionException If get() or send() throws it.
127     */
128    @Override
129    public void fire() throws IllegalActionException {
130        super.fire();
131        Time currentTime = ((DEDirector) getDirector()).getModelTime();
132
133        while (waiter.hasNewToken(0)) {
134            waiter.get(0);
135            _waiting.addElement(currentTime);
136        }
137
138        boolean godot = false;
139
140        while (waitee.hasNewToken(0)) {
141            waitee.get(0);
142            godot = true;
143        }
144
145        if (godot) {
146            for (int i = 0; i < _waiting.size(); i++) {
147                Time previousTime = (Time) _waiting.elementAt(i);
148                DoubleToken outToken = new DoubleToken(
149                        currentTime.subtract(previousTime).getDoubleValue());
150                output.send(0, outToken);
151            }
152
153            _waiting.removeAllElements();
154        }
155    }
156
157    /** Clear the list of waiters.
158     *  @exception IllegalActionException If the parent class throws it.
159     */
160    @Override
161    public void initialize() throws IllegalActionException {
162        super.initialize();
163        _waiting.removeAllElements();
164    }
165
166    ///////////////////////////////////////////////////////////////////
167    ////                         private variables                 ////
168    private Vector _waiting;
169}