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