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 @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                               The new priority of the task.
 133          *
 134          * @exception                   InvalidTaskException is the specified task is not valid. A task
 135          *                                              is invalid if it is not binded with a native task.
 136          */ public void setPrirority(double priority) throws JniException {
 137     MsgNative.taskSetPriority(this, priority);
 138   }
 139   /* *                       * *
 140    * * Communication-related * *
 141     * *                       * *//**
 142     * Retrieves next task on given channel of local host
 143     *
 144     * @exception  JniException if the binding mecanism fails.
 145     * @exception  NativeException if the retrival fails.
 146     */
 147     public static Task get(int channel) throws JniException, NativeException {
 148     return MsgNative.taskGet(channel, -1.0, null);
 149   }
 150    /**
 151     * Retrieves next task on given channel of local host (wait at most #timeout seconds)
 152     *
 153     * @exception  JniException if the binding mecanism fails.
 154     * @exception  NativeException if the retrival fails.
 155     */
 156     public static Task get(int channel, double timeout) throws JniException,
 157     NativeException {
 158     return MsgNative.taskGet(channel, timeout, null);
 159   }
 160    /**
 161     * Retrieves next task from given host on given channel of local host
 162     *
 163     * @exception  JniException if the binding mecanism fails.
 164     * @exception  NativeException if the retrival fails.
 165     */
 166     public static Task get(int channel, Host host) throws JniException,
 167     NativeException {
 168     return MsgNative.taskGet(channel, -1, host);
 169   }
 170    /**
 171     * Retrieves next task from given host on given channel of local host (wait at most #timeout seconds)
 172     *
 173     * @exception  JniException if the binding mecanism fails.
 174     * @exception  NativeException if the retrival fails.
 175     */ public static Task get(int channel, double timeout,
 176                               Host host) throws JniException, NativeException {
 177     return MsgNative.taskGet(channel, timeout, host);
 178   }
 179
 180    /**
 181     * Probes whether there is a waiting task on the given channel of local host
 182     *
 183     * @exception  JniException if the binding mecanism fails.
 184     * @exception  NativeException if the retrival fails.
 185     */ public static boolean probe(int channel) throws JniException {
 186     return MsgNative.taskProbe(channel);
 187   }
 188    /**
 189     * Counts tasks waiting on the given #channel of local host and sent by given #host
 190     *
 191     * @exception  JniException if the binding mecanism fails.
 192     */ public static int probe(int channel, Host host) throws JniException {
 193     return MsgNative.taskProbeHost(channel, host);
 194   }
 195
 196   /* *                     * *
 197    * * Computation-related * *
 198          * *                     * *//**
 199          * This method execute a task on the location on which the
 200          * process is running.
 201          *
 202          * @exception JniException if the binding mecanism fails.
 203          * @exception NativeException if the cancelation failed.
 204          */ public void execute() throws JniException, NativeException {
 205     MsgNative.taskExecute(this);
 206   }
 207         /**
 208          * This method cancels a task.
 209          *
 210          * @exception JniException if the binding mecanism fails.
 211          * @exception NativeException if the cancelation failed.
 212          */ public void cancel() throws JniException, NativeException {
 213     MsgNative.taskCancel(this);
 214   }
 215         /**
 216          * This method deletes a task.
 217          *
 218          * @exception                   InvalidTaskException is the specified task is not valid. A task
 219          *                                              is invalid if it is not binded with a native task.
 220          *                                              MsgException if the destruction failed.
 221          */ protected void finalize() throws JniException, NativeException {
 222     if (this.bind != 0)
 223       MsgNative.taskDestroy(this);
 224         }
 225
 226         /**
 227     * Send the task on the mailbox identified by the default alias (defaultAlias = "currentHostName:CurrentProcessName")
 228     *
 229     * @exception  JniException if the binding mecanism fails.
 230     * @exception  NativeException if the retrival fails.
 231     */
 232         public void send() throws JniException,NativeException {
 233
 234                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 235
 236                 MsgNative.taskSend(alias, this, -1);
 237         }
 238
 239         /**
 240     * Send the task on the mailbox identified by the specified alias
 241     *
 242     * @exception  JniException if the binding mecanism fails.
 243     * @exception  NativeException if the retrival fails.
 244     */
 245         public void send(String alias) throws JniException,NativeException {
 246                 MsgNative.taskSend(alias, this, -1);
 247         }
 248
 249         /**
 250     * Send the task on the mailbox identified by the default alias  (wait at most #timeout seconds)
 251     *
 252     * @exception  JniException if the binding mecanism fails.
 253     * @exception  NativeException if the retrival fails.
 254     */
 255         public void send(double timeout) throws JniException,NativeException {
 256                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 257                 MsgNative.taskSend(alias, this, timeout);
 258         }
 259
 260         /**
 261     * Send the task on the mailbox identified by the specified alias  (wait at most #timeout seconds)
 262     *
 263     * @exception  JniException if the binding mecanism fails.
 264     * @exception  NativeException if the retrival fails.
 265     */
 266         public void send(String alias, double timeout) throws JniException,NativeException {
 267                 MsgNative.taskSend(alias, this, timeout);
 268         }
 269
 270
 271         /**
 272     * Send the task on the mailbox identified by the default alias  (capping the emision rate to #maxrate)
 273     *
 274     * @exception  JniException if the binding mecanism fails.
 275     * @exception  NativeException if the retrival fails.
 276     */
 277         public void sendBounded(double maxrate) throws JniException,NativeException {
 278                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 279                 MsgNative.taskSendBounded(alias, this, maxrate);
 280         }
 281
 282         /**
 283     * Send the task on the mailbox identified by the specified alias  (capping the emision rate to #maxrate)
 284     *
 285     * @exception  JniException if the binding mecanism fails.
 286     * @exception  NativeException if the retrival fails.
 287     */
 288         public void sendBounded(String alias, double maxrate) throws JniException,NativeException {
 289                 MsgNative.taskSendBounded(alias, this, maxrate);
 290         }
 291
 292         /**
 293     * Retrieves next task from the mailbox identified by the default alias (defaultAlias = "currentHostName:CurrentProcessName")
 294     *
 295     * @exception  JniException if the binding mecanism fails.
 296     * @exception  NativeException if the retrival fails.
 297     */
 298         public static Task receive() throws JniException, NativeException {
 299                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 300                 return MsgNative.taskReceive(alias, -1.0, null);
 301         }
 302
 303         /**
 304     * Retrieves next task from the mailbox identified by the specified alias
 305     *
 306     * @exception  JniException if the binding mecanism fails.
 307     * @exception  NativeException if the retrival fails.
 308     */
 309
 310         public static Task receive(String alias) throws JniException, NativeException {
 311                 return MsgNative.taskReceive(alias, -1.0, null);
 312         }
 313
 314         /**
 315     * Retrieves next task on the mailbox identified by the specified alias (wait at most #timeout seconds)
 316     *
 317     * @exception  JniException if the binding mecanism fails.
 318     * @exception  NativeException if the retrival fails.
 319     */
 320         public static Task receive(String alias, double timeout) throws JniException, NativeException {
 321                 return MsgNative.taskReceive(alias, timeout, null);
 322         }
 323
 324         /**
 325     * Retrieves next task sended by a given host on the mailbox identified by the specified alias
 326     *
 327     * @exception  JniException if the binding mecanism fails.
 328     * @exception  NativeException if the retrival fails.
 329     */
 330
 331         public static Task receive(String alias, Host host) throws JniException, NativeException {
 332                 return MsgNative.taskReceive(alias, -1.0, host);
 333         }
 334
 335         /**
 336     * Retrieves next task sended by a given host on the mailbox identified by the specified alias (wait at most #timeout seconds)
 337     *
 338     * @exception  JniException if the binding mecanism fails.
 339     * @exception  NativeException if the retrival fails.
 340     */
 341         public static Task receive(String alias, double timeout, Host host) throws JniException, NativeException {
 342                 return MsgNative.taskReceive(alias, timeout, host);
 343         }
 344
 345         /**
 346     * Listen whether there is a waiting task on the mailbox identified by the default alias of local host
 347     *
 348     * @exception  JniException if the binding mecanism fails.
 349     * @exception  NativeException if the retrival fails.
 350     */
 351         public static boolean listen() throws JniException, NativeException {
 352                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 353
 354                 return MsgNative.taskListen(alias);
 355         }
 356
 357         /**
 358     * Test whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
 359     *
 360     * @exception  JniException if the binding mecanism fails.
 361     * @exception  NativeException if the retrival fails.
 362     */
 363         public static int listenFrom(String alias) throws JniException, NativeException  {
 364                 return MsgNative.taskListenFrom(alias);
 365         }
 366
 367         /**
 368     * Test whether there is a pending communication on the mailbox identified by the default alias, of the current host, and who sent it
 369     *
 370     * @exception  JniException if the binding mecanism fails.
 371     * @exception  NativeException if the retrival fails.
 372     */
 373         public static int listenFrom() throws JniException, NativeException {
 374                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 375
 376                 return MsgNative.taskListenFrom(alias);
 377         }
 378
 379         /**
 380     * Listen whether there is a waiting task on the mailbox identified by the specified alias
 381     *
 382     * @exception  JniException if the binding mecanism fails.
 383     * @exception  NativeException if the retrival fails.
 384     */
 385         public static boolean listen(String alias) throws JniException, NativeException  {
 386                 return MsgNative.taskListen(alias);
 387         }
 388
 389          /**
 390     * Counts the number of tasks waiting to be received on the #mailbox identified by the specified alias and sended by the current host.
 391     *
 392     * @exception  JniException if the binding mecanism fails.
 393     * @exception  NativeException if the retrival fails.
 394     */
 395         public static int listenFromHost(Host host) throws JniException, NativeException  {
 396                 String alias = Host.currentHost().getName() + ":" + Process.currentProcess().msgName();
 397                 return MsgNative.taskListenFromHost(alias,host);
 398         }
 399
 400         /**
 401     * Counts the number of tasks waiting to be received on the #mailbox identified by the specified alia and sended by the specified #host.
 402     *
 403     * @exception  JniException if the binding mecanism fails.
 404     * @exception  NativeException if the retrival fails.
 405     */
 406         public static int listenFromHost(String alias, Host host) throws JniException, NativeException  {
 407                 return MsgNative.taskListenFromHost(alias, host);
 408         }
 409 }