org/simgrid/msg/Task.java

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