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