001/* An interface for objects that can intervene in the execution of actors.
002
003@Copyright (c) 2011-2014 The Regents of the University of California.
004All rights reserved.
005
006Permission is hereby granted, without written agreement and without
007license or royalty fees, to use, copy, modify, and distribute this
008software and its documentation for any purpose, provided that the
009above copyright notice and the following two paragraphs appear in all
010copies of this software.
011
012IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
013FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016SUCH DAMAGE.
017
018THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023ENHANCEMENTS, OR MODIFICATIONS.
024
025                                                PT_COPYRIGHT_VERSION_2
026                                                COPYRIGHTENDKEY
027
028
029 */
030package ptolemy.actor;
031
032import ptolemy.actor.ExecutionAspectListener.ExecutionEventType;
033import ptolemy.actor.util.Time;
034import ptolemy.kernel.util.Decorator;
035import ptolemy.kernel.util.IllegalActionException;
036import ptolemy.kernel.util.NamedObj;
037
038/** An interface for objects that can intervene in the execution of actors.
039 *  A director that executes actors decorated by a resource scheduler has to
040 *  consult the resource scheduler before firing the actor. If the resource
041 *  scheduler returns that there are not enough resources available to
042 *  fire the actor, the firing must be postponed.
043 *  <p>
044 *  For example, a resource scheduler could represent a CPU and actors scheduled
045 *  on a CPU have execution times. The resource scheduler takes care of scheduling
046 *  the actors according to a given scheduling strategy and keeping track of the
047 *  remaining execution times.
048 *
049 *  @author Patricia Derler, Edward A. Lee
050 *  @version $Id$
051 *  @since Ptolemy II 10.0
052 *  @Pt.ProposedRating Red (cxh)
053 *  @Pt.AcceptedRating Red (cxh)
054 */
055public interface ActorExecutionAspect extends Decorator {
056
057    /** Add schedule listener. If necessary, initialize list of actors
058     *  scheduled by this resource scheduler.
059     *  @param listener The listener to be added.
060     *  @exception IllegalActionException If an error occurs in the initialization
061     *  of actors scheduled by this resource scheduler.
062     */
063    public void addExecutingListener(ExecutionAspectListener listener)
064            throws IllegalActionException;
065
066    /** Iterate through all entities deeply contained by the container,
067     *  record for each that it is not executing.
068     *  @exception IllegalActionException If the decorator parameters cannot be read.
069     */
070    public void initializeDecoratedActors() throws IllegalActionException;
071
072    /** Get the execution time of an actor. If the actor does not have an attribute
073     *  specifying the execution time, return the minimum execution time.
074     * @param actor The named object.
075     * @return The execution time.
076     * @exception IllegalActionException Thrown in attribute or token cannot be read.
077     */
078    public double getExecutionTime(NamedObj actor)
079            throws IllegalActionException;
080
081    /** Return whether an actor is currently waiting for a resource.
082     * @param actor The actor that might be waiting for a resource.
083     * @return True if the actor is waiting for a resource.
084     */
085    public boolean isWaitingForResource(Actor actor);
086
087    /** Check whether last actor that was scheduled on this resource
088     *  scheduler finished execution.
089     *  @return True if last actor that requested to be scheduled
090     *  finished.
091     */
092    public boolean lastScheduledActorFinished();
093
094    /** Notify execution listeners about rescheduling events.
095     * @param entity Entity that is being scheduled.
096     * @param time Time when entity is being scheduled.
097     * @param eventType Type of event.
098     */
099    public void notifyExecutionListeners(NamedObj entity, Double time,
100            ExecutionEventType eventType);
101
102    /** Perform rescheduling actions when no new actor requests to be
103     *  scheduled.
104     * @param environmentTime The outside time.
105     * @return Relative time when this Scheduler has to be executed
106     *    again to perform rescheduling actions.
107     * @exception IllegalActionException Thrown in subclasses.
108     */
109    public Time schedule(Time environmentTime) throws IllegalActionException;
110
111    /** Schedule the actor. In this base class, do nothing.  Derived
112     *  classes should schedule the actor.
113     *  @param actor The actor to be scheduled.
114     *  @param environmentTime The current platform time.
115     *  @param deadline The deadline timestamp of the event to be scheduled.
116     *  This can be the same as the environmentTime.
117     *  @param executionTime The execution time of the actor.
118     *  @return Relative time when this Scheduler has to be executed
119     *    again to perform rescheduling actions.  In this base class, null
120     *    is returned.
121     *  @exception IllegalActionException Thrown if actor parameters such
122     *    as execution time or priority cannot be read.
123     */
124    public Time schedule(NamedObj actor, Time environmentTime, Time deadline,
125            Time executionTime) throws IllegalActionException;
126
127    /** Remove schedule listener.
128     * @param listener The listener to be removed.
129     */
130    public void removeExecutionListener(ExecutionAspectListener listener);
131
132}