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