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         /** Default constructor (all fields to 0 or null) */
  30         public Task() {
  31                 create(null, 0, 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 computeDuration       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 >= 0.
  46          *
  47          * @param messageSize           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 >= 0.
  50          */
  51         public Task(String name, double computeDuration, double messageSize) {
  52                 create(name, computeDuration, messageSize);
  53         }
  54         /**
  55          * Construct an 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 computeDurations      The amount of operations to be performed by each host of \a hosts.
  61          * @param messageSizes  A matrix describing the amount of data to exchange between hosts.
  62          */
  63         public Task(String name, Host[]hosts, double[]computeDurations, double[]messageSizes) {
  64                 parallelCreate(name, hosts, computeDurations, messageSizes);
  65         }
  66
  67         /**
  68          * The natively implemented method to create a MSG task.
  69          *
  70          * @param name            The name of th task.
  71          * @param computeDuration    A value of the processing amount (in flop) needed
  72          *                        to process the task. If 0, then it cannot be executed
  73          *                        with the execute() method. This value has to be >= 0.
  74          * @param messageSize        A value of amount of data (in bytes) needed to transfert
  75          *                        this task. If 0, then it cannot be transfered this task.
  76          *                        If 0, then it cannot be transfered with the get() and put()
  77          *                        methods. This value has to be >= 0.
  78          * @exception             IllegalArgumentException if compute duration <0 or message size <0
  79          */
  80         final native void create(String name,
  81                         double computeDuration,
  82                         double messageSize)
  83         throws IllegalArgumentException;
  84         /**
  85          * The natively implemented method to create a MSG parallel task.
  86          *
  87          * @param name                The name of the parallel task.
  88          * @param hosts                The list of hosts implied by the parallel task.
  89          * @param computeDurations    The total number of operations that have to be performed
  90          *                            on the hosts.
  91          * @param messageSizes        An array of doubles
  92          *
  93          */
  94         final native void parallelCreate(String name,
  95                         Host[]hosts,
  96                         double[]computeDurations,
  97                         double[]messageSizes)
  98         throws NullPointerException, IllegalArgumentException;
  99         /* *                   * *
 100          * * Getters / Setters * *
 101          * *                   * */
 102     /**
 103      * Gets the name of a task
 104      */
 105         public String getName() {
 106                 return name;
 107         }
 108         /**
 109          * Gets the sender of the task
 110          * Returns null if the task hasn't been sent yet
 111          */
 112         public native Process getSender();
 113         /** Gets the source of the task.
 114          * Returns null if the task hasn't been sent yet.
 115      */
 116         public native Host getSource();
 117         /** Gets the computing amount of the task
 118      * FIXME: Cache it !
 119      */
 120         public native double getComputeDuration();
 121         /** Gets the remaining computation of the task
 122      */
 123         public native double getRemainingDuration();
 124         /**
 125          * Sets the name of the task
 126          * @param name the new task name.c
 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          * @param computationAmount the amount of computation needed to process the task
 141          */
 142         public native void setComputeDuration(double computationAmount);
 143         /* *                     * *
 144          * * Computation-related * *
 145          * *                     * */
 146         /**
 147          * Executes a task on the location on which the process is running.
 148          *
 149      *
 150      * @throws HostFailureException
 151      * @throws TaskCancelledException
 152      */
 153         public native void execute() throws HostFailureException,TaskCancelledException;
 154         /**
 155          * Cancels a task.
 156          *
 157          */
 158         public native void cancel();
 159         /** Deletes a task.
 160          *
 161          * @exception                   NativeException if the destruction failed.
 162          */
 163         protected void finalize() throws NativeException {
 164                 destroy();
 165         }
 166         /**
 167          * The natively implemented method to destroy a MSG task.
 168          */
 169         protected native void destroy();
 170         /* *                       * *
 171          * * Communication-related * *
 172          * *                       * */
 173
 174         /** Send the task asynchronously on the mailbox identified by the specified name,
 175          *  with no way to retrieve whether the communication succeeded or not
 176          *
 177          */
 178         public native void dsend(String mailbox);
 179         /**
 180          * Sends the task on the mailbox identified by the specified name
 181          *
 182      * @param mailbox
 183      * @throws TimeoutException
 184          * @throws HostFailureException
 185          * @throws TransferFailureException
 186          */
 187         public void send(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
 188                 send(mailbox, -1);
 189         }
 190
 191         /**
 192          * Sends the task on the mailbox identified by the specified name (wait at most \a timeout seconds)
 193          *
 194      * @param mailbox
 195      * @param timeout
 196      * @exception  NativeException if the retrieval fails.
 197          * @throws TimeoutException
 198          * @throws HostFailureException
 199          * @throws TransferFailureException
 200          */
 201         public native void send(String mailbox, double timeout) throws TransferFailureException, HostFailureException, TimeoutException;
 202         /**
 203          * Sends the task on the mailbox identified by the specified alias  (capping the sending rate to \a maxrate)
 204          *
 205      * @param alias
 206      * @param maxrate
 207      * @throws TransferFailureException
 208      * @throws HostFailureException
 209      * @throws TimeoutException
 210          */
 211         public native void sendBounded(String alias, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException;
 212         /**
 213          * Sends the task on the mailbox asynchronously
 214          */
 215         public native Comm isend(String mailbox);
 216
 217         /**
 218          * Starts listening for receiving a task from an asynchronous communication
 219          * @param mailbox
 220          */
 221         public static native Comm irecv(String mailbox);
 222         /**
 223          * Retrieves next task from the mailbox identified by the specified name
 224          *
 225      * @param mailbox
 226          */
 227
 228         public static Task receive(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
 229                 return receive(mailbox, -1.0, null);
 230         }
 231
 232         /**
 233          * Retrieves next task on the mailbox identified by the specified name (wait at most \a timeout seconds)
 234          *
 235      * @param mailbox
 236      * @param timeout
 237          */
 238         public static Task receive(String mailbox, double timeout) throws  TransferFailureException, HostFailureException, TimeoutException {
 239                 return receive(mailbox, timeout, null);
 240         }
 241
 242         /**
 243          * Retrieves next task sent by a given host on the mailbox identified by the specified alias
 244          *
 245      * @param mailbox
 246      * @param host
 247          */
 248
 249         public static Task receive(String mailbox, Host host) throws TransferFailureException, HostFailureException, TimeoutException {
 250                 return receive(mailbox, -1.0, host);
 251         }
 252
 253         /**
 254          * Retrieves next task sent by a given host on the mailbox identified by the specified alias (wait at most \a timeout seconds)
 255          *
 256      * @param mailbox
 257      * @param timeout
 258      * @param host
 259          */
 260         public native static Task receive(String mailbox, double timeout, Host host) throws TransferFailureException, HostFailureException, TimeoutException;
 261         /**
 262          * Tests whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
 263      */
 264         public native static int listenFrom(String mailbox);
 265         /**
 266          * Listen whether there is a waiting task on the mailbox identified by the specified alias
 267      */
 268         public native static boolean listen(String mailbox);
 269
 270         /**
 271          * 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.
 272      */
 273         public native static int listenFromHost(String alias, Host host);
 274
 275         /**
 276          * Class initializer, to initialize various JNI stuff
 277          */
 278         public static native void nativeInit();
 279         static {
 280                 Msg.nativeInit();
 281                 nativeInit();
 282         }
 283 }