src/java/simgrid/msg/Task.java

   1 /*
   2  * simgrid.msg.Task.java        1.00 07/05/01
   3  *
   4  * Copyright 2006,2007 Martin Quinson, Malek Cherier
   5  * All right reserved.
   6  *
   7  * This program is free software; you can redistribute
   8  * it and/or modify it under the terms of the license
   9  *(GNU LGPL) which comes with this package.
  10  */
  11
  12 package simgrid.msg;
  13
  14 /**
  15  * Since most scheduling algorithms rely on a concept of
  16  * task that can be either computed locally or transferred
  17  * on another processor, it seems to be the right level of
  18  * abstraction for our purposes. A task may then be defined
  19  * by a computing amount, a message size and some private
  20  * data. To transfer a task you use an instance of the class
  21  * Channel identified by an number.
  22  *
  23  * @author  Abdelmalek Cherier
  24  * @author  Martin Quinson
  25  * @since SimGrid 3.3
  26  */
  27 public class Task {
  28
  29         /**
  30          * This attribute represents a bind between a java task object and
  31          * a native task. Even if this attribute is public you must never
  32          * access to it. It is set automaticatly during the build of the object.
  33          */
  34   public long bind = 0;
  35
  36
  37   /* Default constructor (disabled) */
  38   protected Task() {
  39   }
  40   /* *              * *
  41    * * Constructors * *
  42          * *              * *//**
  43          * Construct an new task with the specified processing amount and amount
  44          * of data needed.
  45          *
  46          * @param name  Task's name
  47          *
  48          * @param computeDuration       A value of the processing amount (in flop) needed to process the task.
  49          *                              If 0, then it cannot be executed with the execute() method.
  50          *                              This value has to be >= 0.
  51          *
  52          * @param messageSize           A value of amount of data (in bytes) needed to transfert this task.
  53          *                              If 0, then it cannot be transfered with the get() and put() methods.
  54          *                              This value has to be >= 0.
  55          *
  56          * @exception                   JniException if the binding mecanism fails.
  57          */ public Task(String name, double computeDuration,
  58                  double messageSize) throws JniException {
  59     MsgNative.taskCreate(this, name, computeDuration, messageSize);
  60   }
  61     /**
  62      * Construct an new parallel task with the specified processing amount and amount for each host
  63      * implied.
  64      *
  65      * @param name              The name of the parallel task.
  66      * @param hosts             The list of hosts implied by the parallel task.
  67      * @param computeDurations  The amount of operations to be performed by each host of \a hosts.
  68      * @param messageSizes      A matrix describing the amount of data to exchange between hosts.
  69      *
  70      * @exception               JniException if the binding mecanism fails.
  71      */ public Task(String name, Host[]hosts, double[]computeDurations,
  72                     double[]messageSizes) throws JniException {
  73     MsgNative.parallelTaskCreate(this, name, hosts, computeDurations,
  74                                  messageSizes);
  75   }
  76   /* *                   * *
  77    * * Getters / Setters * *
  78          * *                   * *//**
  79          * This method gets the name of a task.
  80          *
  81          * @return                              The name of the task.
  82          *
  83          * @exception                   JniException if the binding mecanism fails.
  84          * @exception                   InvalidTaskException is the specified task is not valid. A task
  85          *                                              is invalid if it is not binded with a native task.
  86          */ public String getName() throws JniException {
  87     return MsgNative.taskGetName(this);
  88   }
  89         /**
  90          * This method gets the sender of the task.
  91          *
  92          * @return                              The sender of the task.
  93          *
  94          * @exception                   JniException if the binding mecanism fails.
  95          *
  96          */ Process getSender() throws JniException {
  97     return MsgNative.taskGetSender(this);
  98   }
  99          /**
 100           * This method gets the source of the task.
 101           *
 102           * @return                             The source of the task.
 103           *
 104           * @exception                  JniException if the binding mecanism fails.
 105           */ public Host getSource() throws JniException, NativeException {
 106     return MsgNative.taskGetSource(this);
 107   }
 108         /**
 109          * This method gets the computing amount of the task.
 110          *
 111          * @return                              The computing amount of the task.
 112          *
 113          * @exception                   JniException if the binding mecanism fails.
 114          */ public double getComputeDuration() throws JniException {
 115     return MsgNative.taskGetComputeDuration(this);
 116   }
 117         /**
 118          * This method gets the remaining computation.
 119          *
 120          * @return                              The remaining duration.
 121          *
 122          * @exception                   JniException if the binding mecanism fails.
 123          */ public double getRemainingDuration() throws JniException {
 124     return MsgNative.taskGetRemainingDuration(this);
 125   }
 126    /**
 127     * This method sets the priority of the computation of the task.
 128     * The priority doesn't affect the transfert rate. For example a
 129     * priority of 2 will make the task receive two times more cpu than
 130     * the other ones.
 131     *
 132     * @param priority   The new priority of the task.
 133     *
 134     * @exception        JniException is the specified task is not valid (ie, not binded to a native task)
 135     */
 136    public void setPriority(double priority) throws JniException {
 137       MsgNative.taskSetPriority(this, priority);
 138    }
 139   /* *                       * *
 140    * * Communication-related * *
 141    * *                       * */
 142
 143    /**
 144     * Retrieves next task on given channel of local host
 145     *
 146     * @exception  JniException if the binding mecanism fails.
 147     * @exception  NativeException if the retrival fails.
 148     */
 149     public static Task get(int channel) throws JniException, NativeException {
 150     return MsgNative.taskGet(channel, -1.0, null);
 151   }
 152    /**
 153     * Retrieves next task on given channel of local host (wait at most \a timeout seconds)
 154     *
 155     * @exception  JniException if the binding mecanism fails.
 156     * @exception  NativeException if the retrival fails.
 157     */
 158     public static Task get(int channel, double timeout) throws JniException,
 159     NativeException {
 160     return MsgNative.taskGet(channel, timeout, null);
 161   }
 162    /**
 163     * Retrieves next task from given host on given channel of local host
 164     *
 165     * @exception  JniException if the binding mecanism fails.
 166     * @exception  NativeException if the retrival fails.
 167     */
 168     public static Task get(int channel, Host host) throws JniException,
 169     NativeException {
 170     return MsgNative.taskGet(channel, -1, host);
 171   }
 172    /**
 173     * Retrieves next task from given host on given channel of local host (wait at most \a timeout seconds)
 174     *
 175     * @exception  JniException if the binding mecanism fails.
 176     * @exception  NativeException if the retrival fails.
 177     */ public static Task get(int channel, double timeout,
 178                               Host host) throws JniException, NativeException {
 179     return MsgNative.taskGet(channel, timeout, host);
 180   }
 181
 182    /**
 183     * Probes whether there is a waiting task on the given channel of local host
 184     *
 185     * @exception  JniException if the binding mecanism fails.
 186     * @exception  NativeException if the retrival fails.
 187     */ public static boolean probe(int channel) throws JniException {
 188     return MsgNative.taskProbe(channel);
 189   }
 190    /**
 191     * Counts tasks waiting on the given \a channel of local host and sent by given \a host
 192     *
 193     * @exception  JniException if the binding mecanism fails.
 194     */ public static int probe(int channel, Host host) throws JniException {
 195     return MsgNative.taskProbeHost(channel, host);
 196   }
 197
 198   /* *                     * *
 199    * * Computation-related * *
 200    * *                     * */
 201   /**
 202    * This method execute a task on the location on which the
 203    * process is running.
 204    *
 205    * @exception JniException if the binding mecanism fails.
 206    * @exception NativeException if the cancelation failed.
 207    */
 208    public void execute() throws JniException, NativeException {
 209       MsgNative.taskExecute(this);
 210    }
 211         /**
 212          * This method cancels a task.
 213          *
 214          * @exception JniException if the binding mecanism fails.
 215          * @exception NativeException if the cancelation failed.
 216          */ public void cancel() throws JniException, NativeException {
 217     MsgNative.taskCancel(this);
 218   }
 219         /**
 220          * This method deletes a task.
 221          *
 222          * @exception                   InvalidTaskException is the specified task is not valid. A task
 223          *                                              is invalid if it is not binded with a native task.
 224          *                                              MsgException if the destruction failed.
 225          */ protected void finalize() throws JniException, NativeException {
 226     if (this.bind != 0)
 227       MsgNative.taskDestroy(this);
 228         }
 229
 230         /**
 231     * Send the task on the mailbox identified by the default alias (defaultAlias = "currentHostName:CurrentProcessName")
 232     *
 233     * @exception  JniException if the binding mecanism fails.
 234     * @exception  NativeException if the retrival fails.
 235     */
 236         public void send() throws JniException,NativeException {
 237
 238                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 239
 240                 MsgNative.taskSend(alias, this, -1);
 241         }
 242
 243         /**
 244     * Send the task on the mailbox identified by the specified alias
 245     *
 246     * @exception  JniException if the binding mecanism fails.
 247     * @exception  NativeException if the retrival fails.
 248     */
 249         public void send(String alias) throws JniException,NativeException {
 250                 MsgNative.taskSend(alias, this, -1);
 251         }
 252
 253         /**
 254     * Send the task on the mailbox identified by the default alias  (wait at most \a timeout seconds)
 255     *
 256     * @exception  JniException if the binding mecanism fails.
 257     * @exception  NativeException if the retrival fails.
 258     */
 259         public void send(double timeout) throws JniException,NativeException {
 260                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 261                 MsgNative.taskSend(alias, this, timeout);
 262         }
 263
 264         /**
 265     * Send the task on the mailbox identified by the specified alias  (wait at most \a timeout seconds)
 266     *
 267     * @exception  JniException if the binding mecanism fails.
 268     * @exception  NativeException if the retrival fails.
 269     */
 270         public void send(String alias, double timeout) throws JniException,NativeException {
 271                 MsgNative.taskSend(alias, this, timeout);
 272         }
 273
 274
 275         /**
 276     * Send the task on the mailbox identified by the default alias  (capping the emision rate to \a maxrate)
 277     *
 278     * @exception  JniException if the binding mecanism fails.
 279     * @exception  NativeException if the retrival fails.
 280     */
 281         public void sendBounded(double maxrate) throws JniException,NativeException {
 282                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 283                 MsgNative.taskSendBounded(alias, this, maxrate);
 284         }
 285
 286         /**
 287     * Send the task on the mailbox identified by the specified alias  (capping the emision rate to \a maxrate)
 288     *
 289     * @exception  JniException if the binding mecanism fails.
 290     * @exception  NativeException if the retrival fails.
 291     */
 292         public void sendBounded(String alias, double maxrate) throws JniException,NativeException {
 293                 MsgNative.taskSendBounded(alias, this, maxrate);
 294         }
 295
 296         /**
 297     * Retrieves next task from the mailbox identified by the default alias (defaultAlias = "currentHostName:CurrentProcessName")
 298     *
 299     * @exception  JniException if the binding mecanism fails.
 300     * @exception  NativeException if the retrival fails.
 301     */
 302         public static Task receive() throws JniException, NativeException {
 303                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 304                 return MsgNative.taskReceive(alias, -1.0, null);
 305         }
 306
 307         /**
 308     * Retrieves next task from the mailbox identified by the specified alias
 309     *
 310     * @exception  JniException if the binding mecanism fails.
 311     * @exception  NativeException if the retrival fails.
 312     */
 313
 314         public static Task receive(String alias) throws JniException, NativeException {
 315                 return MsgNative.taskReceive(alias, -1.0, null);
 316         }
 317
 318         /**
 319     * Retrieves next task on the mailbox identified by the specified alias (wait at most \a timeout seconds)
 320     *
 321     * @exception  JniException if the binding mecanism fails.
 322     * @exception  NativeException if the retrival fails.
 323     */
 324         public static Task receive(String alias, double timeout) throws JniException, NativeException {
 325                 return MsgNative.taskReceive(alias, timeout, null);
 326         }
 327
 328         /**
 329     * Retrieves next task sended by a given host on the mailbox identified by the specified alias
 330     *
 331     * @exception  JniException if the binding mecanism fails.
 332     * @exception  NativeException if the retrival fails.
 333     */
 334
 335         public static Task receive(String alias, Host host) throws JniException, NativeException {
 336                 return MsgNative.taskReceive(alias, -1.0, host);
 337         }
 338
 339         /**
 340     * Retrieves next task sended by a given host on the mailbox identified by the specified alias (wait at most \a timeout seconds)
 341     *
 342     * @exception  JniException if the binding mecanism fails.
 343     * @exception  NativeException if the retrival fails.
 344     */
 345         public static Task receive(String alias, double timeout, Host host) throws JniException, NativeException {
 346                 return MsgNative.taskReceive(alias, timeout, host);
 347         }
 348
 349         /**
 350     * Listen whether there is a waiting task on the mailbox identified by the default alias of local host
 351     *
 352     * @exception  JniException if the binding mecanism fails.
 353     * @exception  NativeException if the retrival fails.
 354     */
 355         public static boolean listen() throws JniException, NativeException {
 356                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 357
 358                 return MsgNative.taskListen(alias);
 359         }
 360
 361         /**
 362     * Test whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
 363     *
 364     * @exception  JniException if the binding mecanism fails.
 365     * @exception  NativeException if the retrival fails.
 366     */
 367         public static int listenFrom(String alias) throws JniException, NativeException  {
 368                 return MsgNative.taskListenFrom(alias);
 369         }
 370
 371         /**
 372     * Test whether there is a pending communication on the mailbox identified by the default alias, of the current host, and who sent it
 373     *
 374     * @exception  JniException if the binding mecanism fails.
 375     * @exception  NativeException if the retrival fails.
 376     */
 377         public static int listenFrom() throws JniException, NativeException {
 378                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 379
 380                 return MsgNative.taskListenFrom(alias);
 381         }
 382
 383    /**
 384     * Listen whether there is a waiting task on the mailbox identified by the specified alias
 385     *
 386     * @exception  JniException if the binding mecanism fails.
 387     * @exception  NativeException if the retrival fails.
 388     */
 389         public static boolean listen(String alias) throws JniException, NativeException  {
 390                 return MsgNative.taskListen(alias);
 391         }
 392
 393    /**
 394     * Counts the number of tasks waiting to be received on the \a mailbox identified by the specified alias and sended by the current host.
 395     *
 396     * @exception  JniException if the binding mecanism fails.
 397     * @exception  NativeException if the retrival fails.
 398     */
 399         public static int listenFromHost(Host host) throws JniException, NativeException  {
 400                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 401                 return MsgNative.taskListenFromHost(alias,host);
 402         }
 403
 404    /**
 405     * Counts the number of tasks waiting to be received on the \a mailbox identified by the specified alia and sended by the specified \a host.
 406     *
 407     * @exception  JniException if the binding mecanism fails.
 408     * @exception  NativeException if the retrival fails.
 409     */
 410         public static int listenFromHost(String alias, Host host) throws JniException, NativeException  {
 411                 return MsgNative.taskListenFromHost(alias, host);
 412         }
 413 }