001/* The interface for DE domain event queues.
002
003 Copyright (c) 1998-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.domains.de.kernel;
029
030import ptolemy.kernel.util.Debuggable;
031import ptolemy.kernel.util.IllegalActionException;
032import ptolemy.kernel.util.InvalidStateException;
033
034///////////////////////////////////////////////////////////////////
035//// DEEventQueue
036
037/**
038 This interface defines an event queue used by DE directors to sort and
039 manage DE events.
040 <p>
041 DE events are sorted according to their timestamps, microsteps, and then the
042 depths of the destination actors. One DE event is said to be earlier than
043 another, if it has a smaller timestamp, or when the timestamps are
044 identical, it has a smaller microstep, or when both time stamps and
045 microsteps are identical, it has a smaller depth. If all three entries are
046 identical, then these two DE events are called identical.
047 <p>
048 This interface defines a few methods to manage the event queue, including
049 adding a new event into the queue, getting the earliest event of the queue.
050 A correct implementation of this interface should not allow identical
051 events. In particular, when adding a new event, the event is not added if
052 the event is already in the queue. Also note that calling the get() method
053 does not delete events from event queue but calling the take() method does.
054
055 @author Lukito Muliadi, Jie Liu, Haiyang Zheng
056 @version $Id$
057 @since Ptolemy II 0.2
058 @Pt.ProposedRating Green (hyzheng)
059 @Pt.AcceptedRating Green (hyzheng)
060 @see DEEvent
061 */
062public interface DEEventQueue extends Debuggable {
063    ///////////////////////////////////////////////////////////////////
064    ////                         public methods                    ////
065
066    /** Empty this event queue.
067     */
068    public void clear();
069
070    /** Return the earliest DE event in this event queue.
071     *  Note that the DE event is not deleted.
072     *  @return The earliest DE event.
073     *  @exception InvalidStateException If the event queue is empty.
074     */
075    public DEEvent get() throws InvalidStateException;
076
077    /** Return true if this event queue is empty.
078     *  @return True if this queue is empty, false otherwise.
079     */
080    public boolean isEmpty();
081
082    /** Enqueue a DE event into the event queue. If the event is already
083     *  contained in the queue, this method does nothing.
084     *  @param event The DE event to be put into the queue.
085     *  @exception IllegalActionException If the event cannot be enqueued.
086     */
087    public void put(DEEvent event) throws IllegalActionException;
088
089    /** Remove an event from the event queue and return true if
090     *  it was removed, and false if it was not in the queue.
091     *  This should only be used for pure events (consequences of
092     *  fireAt()), not for events carrying payloads, because this
093     *  does not remove the payload from the DEReceiver.
094     *  The event passed is an argument need not be exactly the
095     *  same event in the queue. It just has to match the
096     *  actor, timeStamp, microstep, and depth of the event
097     *  to be removed. Implementation of this method is optional.
098     *  @param event The event to enqueue.
099     *  @return True If a match is found and the entry is removed.
100     *  @exception IllegalActionException If the method is not supported.
101     */
102    public boolean remove(DEEvent event) throws IllegalActionException;
103
104    /** Return the size of the event queue.
105     *  @return The size of the event queue.
106     */
107    public int size();
108
109    /** Return the earliest DE event in this event queue. The returned event
110     *  is deleted from the event queue.
111     *  @return The earliest DE event in the event queue.
112     *  @exception InvalidStateException If the queue is empty.
113     */
114    public DEEvent take() throws InvalidStateException;
115
116    /** Return the events currently in the queue as an array.
117     *  @return The events currently in the queue.
118     */
119    public Object[] toArray();
120}