src/bindings/java/org/simgrid/msg/Task.java

   1 /* Copyright (c) 2006-2015. The SimGrid Team.
   2  * All rights reserved.                                                     */
   3
   4 /* This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the license (GNU LGPL) which comes with this package. */
   6
   7 package org.simgrid.msg;
   8
   9 /**
  10  * A task is either something to compute somewhere, or something to exchange between two hosts (or both).
  11  * It is defined by a computing amount and a message size.
  12  *
  13  */
  14 public class Task {
  15         /**
  16          * This attribute represents a bind between a java task object and
  17          * a native task. Even if this attribute is public you must never
  18          * access to it. It is set automatically during the build of the object.
  19          */
  20         private long bind = 0;
  21         /**
  22          * Task name
  23          */
  24         protected String name;
  25
  26         private double messageSize;
  27
  28         static private Long idCpt = 0L;
  29
  30         private Long id;
  31
  32         /** Default constructor (all fields to 0 or null) */
  33         public Task() {
  34                 create(null, 0, 0);
  35                 this.messageSize = 0;
  36                 setId(idCpt);
  37                 idCpt++;
  38         }
  39
  40         /* *              * *
  41          * * Constructors * *
  42          * *              * */
  43         /**
  44          * Construct an new task with the specified processing amount and amount
  45          * of data needed.
  46          *
  47          * @param name  Task's name
  48          *
  49          * @param flopsAmount   A value of the processing amount (in flop) needed to process the task.
  50          *                              If 0, then it cannot be executed with the execute() method.
  51          *                              This value has to be >= 0.
  52          *
  53          * @param bytesAmount           A value of amount of data (in bytes) needed to transfert this task.
  54          *                              If 0, then it cannot be transfered with the get() and put() methods.
  55          *                              This value has to be >= 0.
  56          */
  57         public Task(String name, double flopsAmount, double bytesAmount) {
  58                 create(name, flopsAmount, bytesAmount);
  59                 this.messageSize = bytesAmount;
  60                 setId(idCpt);
  61                 idCpt++;
  62         }
  63         /**
  64          * Construct an new parallel task with the specified processing amount and amount for each host
  65          * implied.
  66          *
  67          * @param name          The name of the parallel task.
  68          * @param hosts         The list of hosts implied by the parallel task.
  69          * @param flopsAmount   The amount of operations to be performed by each host of \a hosts.
  70          * @param bytesAmount   A matrix describing the amount of data to exchange between hosts.
  71          */
  72         public Task(String name, Host[]hosts, double[]flopsAmount, double[]bytesAmount) {
  73                 parallelCreate(name, hosts, flopsAmount, bytesAmount);
  74         }
  75
  76         /**
  77          * The natively implemented method to create a MSG task.
  78          *
  79          * @param name            The name of th task.
  80          * @param flopsAmount    A value of the processing amount (in flop) needed
  81          *                        to process the task. If 0, then it cannot be executed
  82          *                        with the execute() method. This value has to be >= 0.
  83          * @param bytesAmount        A value of amount of data (in bytes) needed to transfert
  84          *                        this task. If 0, then it cannot be transfered this task.
  85          *                        If 0, then it cannot be transfered with the get() and put()
  86          *                        methods. This value has to be >= 0.
  87          * @exception             IllegalArgumentException if compute duration <0 or message size <0
  88          */
  89         private final native void create(String name,
  90                         double flopsAmount,
  91                         double bytesAmount)
  92         throws IllegalArgumentException;
  93         /**
  94          * The natively implemented method to create a MSG parallel task.
  95          *
  96          * @param name                The name of the parallel task.
  97          * @param hosts                The list of hosts implied by the parallel task.
  98          * @param flopsAmount         The total number of operations that have to be performed
  99          *                            on the hosts.
 100          * @param bytesAmount        An array of doubles
 101          *
 102          */
 103         private final native void parallelCreate(String name,
 104                         Host[]hosts,
 105                         double[]flopsAmount,
 106                         double[]bytesAmount)
 107         throws NullPointerException, IllegalArgumentException;
 108         /* *                   * *
 109          * * Getters / Setters * *
 110          * *                   * */
 111     /** Gets the name of a task */
 112         public String getName() {
 113                 return name;
 114         }
 115
 116         /** Gets the sender of the task (or null if not sent yet) */
 117         public native Process getSender();
 118
 119         /** Gets the source of the task (or null if not sent yet). */
 120         public native Host getSource();
 121
 122         /** Gets the remaining amount of flops to execute in this task
 123          *
 124          * If it's ongoing, you get the exact amount at the present time. If it's already done, it's 0.
 125          */
 126         public native double getFlopsAmount();
 127         /**
 128          * Sets the name of the task
 129          * @param name the new task name
 130          */
 131         public native void setName(String name);
 132         /**
 133          * This method sets the priority of the computation of the task.
 134          * The priority doesn't affect the transfer rate. For example a
 135          * priority of 2 will make the task receive two times more cpu than
 136          * the other ones.
 137          *
 138          * @param priority      The new priority of the task.
 139          */
 140         public native void setPriority(double priority);
 141
 142         /** Set the computation amount needed to process the task
 143          *
 144          * Warning if the execution is already started and ongoing, this call does nothing.
 145          * @param flopsAmount the amount of computation needed to process the task
 146          */
 147         public native void setFlopsAmount(double flopsAmount);
 148         /**
 149          * Set the amount of bytes to exchange the task
 150          *
 151          * Warning if the communication is already started and ongoing, this call does nothing.
 152          * @param bytesAmount the size of the task
 153          */
 154         public native void setBytesAmount(double bytesAmount);
 155         /* *                     * *
 156          * * Computation-related * *
 157          * *                     * */
 158         /**
 159          * Executes a task on the location on which the current process is running.
 160      *
 161      * @throws HostFailureException
 162      * @throws TaskCancelledException
 163      */
 164         public native void execute() throws HostFailureException,TaskCancelledException;
 165
 166         /** Bound a computation to a certain load */
 167         public native void setBound(double load);
 168
 169         /** Cancels a task. */
 170         public native void cancel();
 171
 172         /** Deletes a task.
 173          *
 174          * @exception                   NativeException if the destruction failed.
 175          */
 176         protected void finalize() throws NativeException {
 177                 destroy();
 178         }
 179         /**
 180          * The natively implemented method to destroy a MSG task.
 181          */
 182         protected native void destroy();
 183         /* *                       * *
 184          * * Communication-related * *
 185          * *                       * */
 186
 187         /** Send the task asynchronously on the mailbox identified by the specified name,
 188          *  with no way to retrieve whether the communication succeeded or not
 189          *
 190          */
 191         public native void dsendBounded(String mailbox, double maxrate);
 192
 193
 194         /** Send the task asynchronously on the mailbox identified by the specified name,
 195          *  with no way to retrieve whether the communication succeeded or not
 196          *
 197          */
 198         public native void dsend(String mailbox);
 199
 200         /**
 201          * Sends the task on the mailbox identified by the specified name
 202          *
 203      * @param mailbox
 204      * @throws TimeoutException
 205          * @throws HostFailureException
 206          * @throws TransferFailureException
 207          */
 208         public void send(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
 209                 send(mailbox, -1);
 210         }
 211
 212         /**
 213          * Sends the task on the mailbox identified by the specified name (wait at most \a timeout seconds)
 214          *
 215      * @param mailbox
 216      * @param timeout
 217      * @exception  NativeException if the retrieval fails.
 218          * @throws TimeoutException
 219          * @throws HostFailureException
 220          * @throws TransferFailureException
 221          */
 222         public native void send(String mailbox, double timeout) throws TransferFailureException, HostFailureException, TimeoutException;
 223         /**
 224          * Sends the task on the mailbox identified by the specified alias  (capping the sending rate to \a maxrate)
 225          *
 226      * @param alias
 227      * @param maxrate
 228      * @throws TransferFailureException
 229      * @throws HostFailureException
 230      * @throws TimeoutException
 231          */
 232         public void sendBounded(String alias, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException {
 233               sendBounded(alias,-1,maxrate);
 234         }
 235
 236
 237 /**
 238          * Sends the task on the mailbox identified by the specified alias  (capping the sending rate to \a maxrate) with a timeout
 239          *
 240      * @param alias
 241      * @param timeout
 242      * @param maxrate
 243      * @throws TransferFailureException
 244      * @throws HostFailureException
 245      * @throws TimeoutException
 246          */
 247         public native void sendBounded(String alias, double timeout, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException;
 248
 249
 250         /**
 251          * Sends the task on the mailbox asynchronously
 252          */
 253         public native Comm isend(String mailbox);
 254
 255         /**
 256          * Sends the task on the mailbox asynchronously (capping the sending rate to \a maxrate)
 257          */
 258         public native Comm isendBounded(String mailbox, double maxrate);
 259
 260
 261         /**
 262          * Starts listening for receiving a task from an asynchronous communication
 263          * @param mailbox
 264          */
 265         public static native Comm irecv(String mailbox);
 266         /**
 267          * Retrieves next task from the mailbox identified by the specified name
 268          *
 269      * @param mailbox
 270          */
 271
 272         public static Task receive(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
 273                 return receive(mailbox, -1.0, null);
 274         }
 275
 276         /**
 277          * Retrieves next task on the mailbox identified by the specified name (wait at most \a timeout seconds)
 278          *
 279      * @param mailbox
 280      * @param timeout
 281          */
 282         public static Task receive(String mailbox, double timeout) throws  TransferFailureException, HostFailureException, TimeoutException {
 283                 return receive(mailbox, timeout, null);
 284         }
 285
 286         /**
 287          * Retrieves next task sent by a given host on the mailbox identified by the specified alias
 288          *
 289      * @param mailbox
 290      * @param host
 291          */
 292
 293         public static Task receive(String mailbox, Host host) throws TransferFailureException, HostFailureException, TimeoutException {
 294                 return receive(mailbox, -1.0, host);
 295         }
 296
 297         /**
 298          * Retrieves next task sent by a given host on the mailbox identified by the specified alias (wait at most \a timeout seconds)
 299          *
 300      * @param mailbox
 301      * @param timeout
 302      * @param host
 303          */
 304         public native static Task receive(String mailbox, double timeout, Host host) throws TransferFailureException, HostFailureException, TimeoutException;
 305
 306         /**
 307          * Starts listening for receiving a task from an asynchronous communication with a capped rate
 308          * @param mailbox
 309          */
 310         public static native Comm irecvBounded(String mailbox, double rate);
 311         /**
 312          * Retrieves next task from the mailbox identified by the specified name with a capped rate
 313          *
 314      * @param mailbox
 315          */
 316
 317         public static Task receiveBounded(String mailbox, double rate) throws TransferFailureException, HostFailureException, TimeoutException {
 318                 return receiveBounded(mailbox, -1.0, null, rate);
 319         }
 320
 321         /**
 322          * Retrieves next task on the mailbox identified by the specified name (wait at most \a timeout seconds) with a capped rate
 323          *
 324      * @param mailbox
 325      * @param timeout
 326          */
 327         public static Task receiveBounded(String mailbox, double timeout, double rate) throws  TransferFailureException, HostFailureException, TimeoutException {
 328                 return receiveBounded(mailbox, timeout, null, rate);
 329         }
 330
 331         /**
 332          * Retrieves next task sent by a given host on the mailbox identified by the specified alias with a capped rate
 333          *
 334      * @param mailbox
 335      * @param host
 336          */
 337
 338         public static Task receiveBounded(String mailbox, Host host, double rate) throws TransferFailureException, HostFailureException, TimeoutException {
 339                 return receiveBounded(mailbox, -1.0, host, rate);
 340         }
 341
 342         /**
 343          * Retrieves next task sent by a given host on the mailbox identified by the specified alias (wait at most \a timeout seconds)
 344          * with a capped rate
 345          *
 346      * @param mailbox
 347      * @param timeout
 348      * @param host
 349          */
 350         public native static Task receiveBounded(String mailbox, double timeout, Host host, double rate) throws TransferFailureException, HostFailureException, TimeoutException;
 351
 352
 353
 354         /**
 355          * Tests whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
 356      */
 357         public native static int listenFrom(String mailbox);
 358         /**
 359          * Listen whether there is a waiting task on the mailbox identified by the specified alias
 360      */
 361         public native static boolean listen(String mailbox);
 362
 363         /**
 364          * 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.
 365      */
 366         public native static int listenFromHost(String alias, Host host);
 367
 368         /**
 369          * Class initializer, to initialize various JNI stuff
 370          */
 371         public static native void nativeInit();
 372         static {
 373                 Msg.nativeInit();
 374                 nativeInit();
 375         }
 376
 377         public double getMessageSize() {
 378                 return this.messageSize;
 379         }
 380
 381         public Long getId() {
 382                 return id;
 383         }
 384
 385         public void setId(Long id) {
 386                 this.id = id;
 387         }
 388 }