001/* Interface for directors with a period parameter.
002
003 Copyright (c) 2000-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 PT_COPYRIGHT_VERSION_2
024 COPYRIGHTENDKEY
025
026 */
027
028package ptolemy.actor.util;
029
030import ptolemy.actor.Executable;
031import ptolemy.kernel.util.IllegalActionException;
032import ptolemy.kernel.util.Nameable;
033
034///////////////////////////////////////////////////////////////////
035//// PeriodicDirector
036
037/**
038 Interface for directors that have a <i>period</i> parameter.
039 These directors are, by default, untimed, but become timed when
040 the <i>period</i> parameter is given a value other than 0.0.
041 The <i>period</i> parameter, if non-zero, specifies the
042 amount of model time that elapses per iteration.
043 In this case, the director should fire only at times
044 that are multiples of the <i>period</i>. If the director is
045 at the top level, then it is responsible for incrementing time
046 between iterations. Otherwise, it is responsible for invoking
047 fireAt() on the enclosing executive director to request
048 subsequent firings, and refusing to fire (by returning false
049 from prefire()) at times that are not multiples of the <i>period</i>.
050
051 @author Edward A. Lee
052 @version $Id$
053 @since Ptolemy II 8.0
054 @Pt.ProposedRating Yellow (eal)
055 @Pt.AcceptedRating Red (eal)
056 */
057public interface PeriodicDirector extends Executable, Nameable {
058
059    ///////////////////////////////////////////////////////////////////
060    ////                         public methods                    ////
061
062    /** Return true if this director is embedded inside an opaque composite
063     *  actor contained by another composite actor. Note that some classes,
064     *  such as RunCompositeActor, may return false even if they are actually
065     *  embedded, but they want to be treated as if they were not.
066     *  @return True if this directory is embedded inside an opaque composite
067     *  actor contained by another composite actor.
068     */
069    public boolean isEmbedded();
070
071    /** Return the value of the period as a double.
072     *  @return The value of the period as a double.
073     *  @exception IllegalActionException If the period parameter
074     *   cannot be evaluated
075     */
076    public double periodValue() throws IllegalActionException;
077}