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