contrib/psg/src/peersim/core/Scheduler.java

   1 /*
   2  * Copyright (c) 2003-2005 The BISON Project
   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.core;
  20
  21 import peersim.config.*;
  22
  23 // XXX a quite primitive scheduler, should be able to be configured
  24 // much more flexibly using a simple syntax for time ranges.
  25 /**
  26 * A binary function over the time points. That is,
  27 * for each time point returns a boolean value.
  28 *
  29 * The concept of time depends on the simulation model. Current time
  30 * has to be set by the simulation engine, irrespective of the model,
  31 * and can be read using {@link CommonState#getTime()}. This scheduler
  32 * is interpreted over those time points.
  33 *
  34 * <p>In this simple implementation the valid times will be
  35 * <tt>from, from+step, from+2*step, etc,</tt>
  36 * where the last element is strictly less than <tt>until</tt>.
  37 * Alternatively, if <tt>at</tt> is defined, then the schedule will be a single
  38 * time point. If FINAL is
  39 * defined, it is also added to the set of active time points.
  40 * It refers to the time after the simulation has finished (see
  41 * {@link CommonState#getPhase}).
  42 */
  43 public class Scheduler {
  44
  45
  46 // ========================= fields =================================
  47 // ==================================================================
  48
  49
  50 /**
  51 * Defaults to 1.
  52 * @config
  53 */
  54 private static final String PAR_STEP = "step";
  55
  56 /**
  57 * Defaults to -1. That is, defaults to be ineffective.
  58 * @config
  59 */
  60 private static final String PAR_AT = "at";
  61
  62
  63 /**
  64 * Defaults to 0.
  65 * @config
  66 */
  67 private static final String PAR_FROM = "from";
  68
  69 /**
  70 * Defaults to <tt>Long.MAX_VALUE</tt>.
  71 * @config
  72 */
  73 private static final String PAR_UNTIL = "until";
  74
  75 /**
  76 * Defines if component is active after the simulation has finished.
  77 * Note that the exact time the simulation finishes is not know in advance
  78 * because other components can stop the simulation at any time.
  79 * By default not set.
  80 * @see CommonState#getPhase
  81 * @config
  82 */
  83 private static final String PAR_FINAL = "FINAL";
  84
  85 public final long step;
  86
  87 public final long from;
  88
  89 public final long until;
  90
  91 public final boolean fin;
  92
  93 /** The next scheduled time point.*/
  94 protected long next = -1;
  95
  96 // ==================== initialization ==============================
  97 // ==================================================================
  98
  99
 100 /** Reads configuration parameters from the component defined by
 101 * <code>prefix</code>. {@value #PAR_STEP} defaults to 1.
 102 */
 103 public Scheduler(String prefix) {
 104
 105         this(prefix, true);
 106 }
 107
 108 // ------------------------------------------------------------------
 109
 110 /** Reads configuration parameters from the component defined by
 111 * <code>prefix</code>. If useDefault is false, then at least parameter
 112 * {@value #PAR_STEP} must be explicitly defined. Otherwise {@value #PAR_STEP}
 113 * defaults to 1.
 114 */
 115 public Scheduler(String prefix, boolean useDefault)
 116 {
 117         if (Configuration.contains(prefix+"."+PAR_AT)) {
 118                 // FROM, UNTIL, and STEP should *not* be defined
 119                 if (Configuration.contains(prefix+"."+PAR_FROM) ||
 120                                 Configuration.contains(prefix+"."+PAR_UNTIL) ||
 121                                 Configuration.contains(prefix+"."+PAR_STEP))
 122                         throw new IllegalParameterException(prefix,
 123                                 "Cannot use \""+PAR_AT+"\" together with \""
 124                                 +PAR_FROM+"\", \""+PAR_UNTIL+"\", or \""+
 125                                 PAR_STEP+"\"");
 126
 127                 from = Configuration.getLong(prefix+"."+PAR_AT);
 128                 until = from+1;
 129                 step = 1;
 130         } else {
 131                 if (useDefault)
 132                         step = Configuration.getLong(prefix+"."+PAR_STEP,1);
 133                 else
 134                         step = Configuration.getLong(prefix+"."+PAR_STEP);
 135                 if( step < 1 )
 136                         throw new IllegalParameterException(prefix,
 137                                 "\""+PAR_STEP+"\" must be >= 1");
 138
 139                 from = Configuration.getLong(prefix+"."+PAR_FROM,0);
 140                 until = Configuration.getLong(prefix+"."+PAR_UNTIL,Long.MAX_VALUE);
 141         }
 142
 143         if( from < until ) next = from;
 144         else next = -1;
 145
 146         fin = Configuration.contains(prefix+"."+PAR_FINAL);
 147 }
 148
 149
 150 // ===================== public methods ==============================
 151 // ===================================================================
 152
 153 /** true if given time point is covered by this scheduler */
 154 public boolean active(long time) {
 155
 156         if( time < from || time >= until ) return false;
 157         return (time - from)%step == 0;
 158 }
 159
 160 // -------------------------------------------------------------------
 161
 162 /** true if current time point is covered by this scheduler */
 163 public boolean active() {
 164
 165         return active( CommonState.getTime() );
 166 }
 167
 168 //-------------------------------------------------------------------
 169
 170 /**
 171 * Returns the next time point. If the returned value is negative, there are
 172 * no more time points. As a side effect, it also updates the next time point,
 173 * so repeated calls to this method return the scheduled times.
 174 */
 175 public long getNext()
 176 {
 177         long ret = next;
 178         // check like this to prevent integer overflow of "next"
 179         if( until-next > step ) next += step;
 180         else next = -1;
 181         return ret;
 182 }
 183
 184 }
 185
 186