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