contrib/psg/src/peersim/edsim/PriorityQ.java

   1 /*
   2  * Copyright (c)2008 The Peersim Team
   3  *
   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.
   7  *
   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.
  12  *
  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.
  16  *
  17  */
  18
  19 package peersim.edsim;
  20
  21 import peersim.core.Node;
  22
  23 /**
  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.
  28  */
  29 public interface PriorityQ {
  30
  31
  32 /**
  33  * Returns the current number of events in the queue.
  34  */
  35 public int size();
  36
  37 /**
  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.
  41  *
  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
  47  */
  48 public void add(long time, Object event, Node node, byte pid);
  49
  50 /**
  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.
  55  *
  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.
  64  */
  65 public void add(long time, Object event, Node node, byte pid, long priority);
  66
  67 /**
  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
  73  */
  74 public Event removeFirst();
  75
  76 /**
  77 * Maximal value of time this interpretation can represent.
  78 */
  79 public long maxTime();
  80
  81 /**
  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)
  86 */
  87 public long maxPriority();
  88
  89 /**
  90  * Return type of {@link #removeFirst()}.
  91  */
  92 public class Event
  93 {
  94         public Object event;
  95         public long time;
  96         public Node node;
  97         public byte pid;
  98         public String toString() {
  99                 return event+" to node "+node+"prot "+pid+"at "+time; }
 100 }
 101
 102 }