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

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