2 * Copyright (c)2008 The Peersim Team
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License version 2 as
6 * published by the Free Software Foundation.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
19 package peersim.edsim;
21 import peersim.core.Node;
24 * The interface to be implemented by the event queue of the evend based
25 * engine. An implementation must also provide the standard cosntructor
26 * required by any peersim components: one that takes a String argument,
27 * the component name in the configuration.
29 public interface PriorityQ {
33 * Returns the current number of events in the queue.
38 * Add a new event, to be scheduled at the specified time. If there are other
39 * events scheduled at the same time, then the time of execution if this event
40 * relative to the other events is unspecified.
42 * @param time The time at which this event should be scheduled. It is
43 * guaranteed to be non-negative (so no extra checks are needed)
44 * @param event the object describing the event
45 * @param node the node at which the event has to be delivered
46 * @param pid the protocol that handles the event
48 public void add(long time, Object event, Node node, byte pid);
51 * Add a new event, to be scheduled at the specified time, specifying also
52 * the priority of the event, should there be other events scheduled at the
53 * same time. If both time and priority is the same for an event, then the
54 * scheduling order is unspecified.
56 * @param time The time at which this event should be scheduled. It is
57 * guaranteed to be non-negative (so no extra checks are needed)
58 * @param event the object describing the event
59 * @param node the node at which the event has to be delivered
60 * @param pid the protocol that handles the event
61 * @param priority if for two events the "time" value is the same, this
62 * value should be used to order them. Lower value means higher priority.
63 * Like with time, non-negativity as assumed.
65 public void add(long time, Object event, Node node, byte pid, long priority);
68 * Removes the first event in the heap and returns it.
69 * The returned object is not guaranteed to be a freshly generated object,
70 * that is, we allow for an implementation that keeps one copy of an event
71 * object and always returns a reference to that copy.
72 * @return first event or null if size is zero
74 public Event removeFirst();
77 * Maximal value of time this interpretation can represent.
79 public long maxTime();
82 * Maximal value of priority this interpretation can deal with. That is,
83 * the number of different priority levels is <tt>maxPriority()+1</tt> because
84 * 0 is also a valid level.
85 * @see #add(long,Object,Node,byte,long)
87 public long maxPriority();
90 * Return type of {@link #removeFirst()}.
98 public String toString() {
99 return event+" to node "+node+"prot "+pid+"at "+time; }