001/* An actor that pauses a model executing when it receives a true token.
002
003 Copyright (c) 1997-2014 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.lib;
029
030import ptolemy.data.BooleanToken;
031import ptolemy.data.expr.SingletonParameter;
032import ptolemy.data.type.BaseType;
033import ptolemy.kernel.CompositeEntity;
034import ptolemy.kernel.util.IllegalActionException;
035import ptolemy.kernel.util.NameDuplicationException;
036import ptolemy.kernel.util.Settable;
037
038///////////////////////////////////////////////////////////////////
039//// Stop
040
041/** An actor that pauses execution of a model when it receives a true
042 token on any input channel. This is accomplished by calling
043 pause() on the manager.
044
045
046 @author Patricia Derler
047 @version $Id$
048 @since Ptolemy II 10.0
049 @Pt.ProposedRating Red (pd)
050 @Pt.AcceptedRating Red (pd)
051 */
052public class Pause extends Sink {
053
054    /** Construct an actor in the specified container with the specified
055     *  name.
056     *  @param container The container.
057     *  @param name The name of this actor within the container.
058     *  @exception IllegalActionException If the actor cannot be contained
059     *   by the proposed container.
060     *  @exception NameDuplicationException If the name coincides with
061     *   an actor already in the container.
062     */
063    public Pause(CompositeEntity container, String name)
064            throws IllegalActionException, NameDuplicationException {
065        super(container, name);
066
067        input.setTypeEquals(BaseType.BOOLEAN);
068
069        // Icon is a stop sign.
070        _attachText("_iconDescription", "<svg>\n"
071                + "<polygon points=\"-8,-19 8,-19 19,-8 19,8 8,19 "
072                + "-8,19 -19,8 -19,-8\" " + "style=\"fill:cyan\"/>\n"
073                + "<text x=\"-15\" y=\"4\""
074                + "style=\"font-size:11; fill:black; font-family:SansSerif\">"
075                + "PAUSE</text>\n" + "</svg>\n");
076
077        // Hide the name because the name is in the icon.
078        _hideName = new SingletonParameter(this, "_hideName");
079        _hideName.setToken(BooleanToken.TRUE);
080        _hideName.setVisibility(Settable.EXPERT);
081    }
082
083    ///////////////////////////////////////////////////////////////////
084    ////                     ports and parameters                  ////
085
086    /** The parameter that hides the name of the actor.  The default
087     * value is true.
088     */
089    public SingletonParameter _hideName;
090
091    ///////////////////////////////////////////////////////////////////
092    ////                         public methods                    ////
093
094    /** Read one token from each input channel that has a token,
095     *  and if any token is true, call pause() on the manager.
096     *  If nothing at all is connected to the input port, then
097     *  do nothing.
098     *  @exception IllegalActionException If there is no director or
099     *   if there is no manager, or if the container is not a
100     *   CompositeActor.
101     *  @return False if this actor is trying to pause execution if any
102     *  token is true or if the input is not connected.  If this actor
103     *  is not trying to pause execution, then return the value
104     *  returned by super.postfire().
105     */
106    @Override
107    public boolean postfire() throws IllegalActionException {
108        boolean result = false;
109
110        if (!input.isOutsideConnected()) {
111            result = true;
112        }
113
114        // NOTE: We need to consume data on all channels that have data.
115        // If we don't then DE will go into an infinite loop.
116        for (int i = 0; i < input.getWidth(); i++) {
117            if (input.hasToken(i)) {
118                if (((BooleanToken) input.get(i)).booleanValue()) {
119                    result = true;
120                }
121            }
122        }
123
124        if (result) {
125            getManager().pause();
126
127        }
128
129        // If this actor is not trying to stop execution, then return
130        // the value returned by super.postfire().
131        boolean superResults = super.postfire();
132        if (!result) {
133            return superResults;
134        }
135
136        return !result;
137    }
138}