001/* A simple sink actor that consumes and discards input tokens.
002
003 Copyright (c) 1998-2016 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 java.net.URL;
031import java.util.HashSet;
032import java.util.Set;
033
034import ptolemy.data.type.BaseType;
035import ptolemy.data.type.TypeConstant;
036import ptolemy.graph.Inequality;
037import ptolemy.kernel.CompositeEntity;
038import ptolemy.kernel.util.Configurable;
039import ptolemy.kernel.util.IllegalActionException;
040import ptolemy.kernel.util.NameDuplicationException;
041
042///////////////////////////////////////////////////////////////////
043//// Discard
044
045/**
046 A simple sink actor that consumes and discards input tokens.
047 <p>This actor is useful in situations where the value of an output is not
048 needed, but for some reason, the output cannot be left unconnected.
049 Also, when manipulating bus signals, this actor is useful if values
050 in the middle of the bus need to be discarded.  Leaving the bus
051 unconnected in the middle will not work because no channel is allocated
052 to an unconnected relation in a bus.
053
054 @author Edward A. Lee, contributors: Christopher Brooks, Brian Hudson
055 @version $Id$
056 @since Ptolemy II 1.0
057 @Pt.ProposedRating Yellow (eal)
058 @Pt.AcceptedRating Yellow (ssachs)
059 */
060public class Discard extends Sink implements Configurable {
061
062    /** Construct an actor with an input multiport.
063     *  @param container The container.
064     *  @param name The name of this actor.
065     *  @exception IllegalActionException If the actor cannot be contained
066     *   by the proposed container.
067     *  @exception NameDuplicationException If the container already has an
068     *   actor with this name.
069     */
070    public Discard(CompositeEntity container, String name)
071            throws NameDuplicationException, IllegalActionException {
072        super(container, name);
073    }
074
075    ///////////////////////////////////////////////////////////////////
076    ////                         public methods                    ////
077
078    /** Do nothing, as this actor is not actually configurable.
079     *  <p>This class implements {@link ptolemy.kernel.util.Configurable}
080     *  so that the MoML filters can replace graphical actors that
081     *  implement Configurable with this actor.  Note that the actors
082     *  to be replaced must have an input port named <i>input</i>, so
083     *  not all Configurable actors can be replaced with this actor.
084     *  @param base Ignored.
085     *  @param source Ignored.
086     *  @param text Ignored.
087     *  @exception Exception Not thrown in this base class.
088     */
089    @Override
090    public void configure(URL base, String source, String text)
091            throws Exception {
092    }
093
094    /** Read one token from each input channel and discard it.
095     *  If there is no input on a channel, then skip that channel, doing
096     *  nothing with it.
097     *  @exception IllegalActionException If there is no director.
098     */
099    @Override
100    public void fire() throws IllegalActionException {
101        super.fire();
102        int width = input.getWidth();
103
104        for (int i = 0; i < width; i++) {
105            if (input.hasToken(i)) {
106                input.get(i);
107            }
108        }
109    }
110
111    /** Return null because this actor is not actually configurable.
112     *  @return Always return null.
113     */
114    @Override
115    public String getConfigureSource() {
116        return null;
117    }
118
119    /** Return null because this actor is not actually configurable.
120     *  @return Always return null.
121     */
122    @Override
123    public String getConfigureText() {
124        return null;
125    }
126    ///////////////////////////////////////////////////////////////////
127    ////                         protected methods                 ////
128
129    /** Set the input port greater than or equal to
130     *  <code>BaseType.GENERAL</code> in case backward type inference is
131     *  enabled and the input port has no type declared.
132     *
133     *  @return A set of inequalities.
134     */
135    @Override
136    protected Set<Inequality> _customTypeConstraints() {
137        HashSet<Inequality> result = new HashSet<Inequality>();
138        if (isBackwardTypeInferenceEnabled()
139                && input.getTypeTerm().isSettable()) {
140            result.add(new Inequality(new TypeConstant(BaseType.GENERAL),
141                    input.getTypeTerm()));
142        }
143        return result;
144    }
145}