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

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