src/java/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 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 (disabled) */
  29         protected Task() {}
  30         /* *              * *
  31          * * Constructors * *
  32          * *              * */
  33         /**
  34          * Construct an new task with the specified processing amount and amount
  35          * of data needed.
  36          *
  37          * @param name  Task's name
  38          *
  39          * @param computeDuration       A value of the processing amount (in flop) needed to process the task.
  40          *                              If 0, then it cannot be executed with the execute() method.
  41          *                              This value has to be >= 0.
  42          *
  43          * @param messageSize           A value of amount of data (in bytes) needed to transfert this task.
  44          *                              If 0, then it cannot be transfered with the get() and put() methods.
  45          *                              This value has to be >= 0.
  46          *
  47          * @exception                   JniException if the binding mechanism fails.
  48          */
  49         public Task(String name, double computeDuration, double messageSize) throws JniException {
  50                 MsgNative.taskCreate(this, name, computeDuration, messageSize);
  51         }
  52         /**
  53          * Construct an new parallel task with the specified processing amount and amount for each host
  54          * implied.
  55          *
  56          * @param name          The name of the parallel task.
  57          * @param hosts         The list of hosts implied by the parallel task.
  58          * @param computeDurations      The amount of operations to be performed by each host of \a hosts.
  59          * @param messageSizes  A matrix describing the amount of data to exchange between hosts.
  60          *
  61          * @exception           JniException if the binding mecanism fails.
  62          */
  63         public Task(String name, Host[]hosts, double[]computeDurations, double[]messageSizes) throws JniException {
  64                 MsgNative.parallelTaskCreate(this, name, hosts, computeDurations, messageSizes);
  65         }
  66         /* *                   * *
  67          * * Getters / Setters * *
  68          * *                   * */
  69         /** gets the name of a task.
  70          * @exception                   JniException if the binding mechanism fails.
  71          */
  72         public String getName() throws JniException {
  73                 return MsgNative.taskGetName(this);
  74         }
  75         /** gets the sender of the task.
  76          * @exception                   JniException if the binding mechanism fails.
  77          *
  78          */
  79         Process getSender() throws JniException {
  80                 return MsgNative.taskGetSender(this);
  81         }
  82         /** Gets the source of the task.
  83          * @exception                   JniException if the binding mechanism fails.
  84          */
  85         public Host getSource() throws JniException, NativeException {
  86                 return MsgNative.taskGetSource(this);
  87         }
  88         /** gets the computing amount of the task.
  89          * @exception                   JniException if the binding mechanism fails.
  90          */
  91         public double getComputeDuration() throws JniException {
  92                 return MsgNative.taskGetComputeDuration(this);
  93         }
  94         /** gets the remaining computation of the task.
  95          * @exception                   JniException if the binding mechanism fails.
  96          */
  97         public double getRemainingDuration() throws JniException {
  98                 return MsgNative.taskGetRemainingDuration(this);
  99         }
 100         /**
 101          * This method sets the priority of the computation of the task.
 102          * The priority doesn't affect the transfert rate. For example a
 103          * priority of 2 will make the task receive two times more cpu than
 104          * the other ones.
 105          *
 106          * @param priority      The new priority of the task.
 107          *
 108          * @exception   JniException is the specified task is not valid (ie, not binded to a native task)
 109          */
 110         public void setPriority(double priority) throws JniException {
 111                 MsgNative.taskSetPriority(this, priority);
 112         }
 113         /* *                       * *
 114          * * Communication-related * *
 115          * *                       * */
 116
 117
 118         /* *                     * *
 119          * * Computation-related * *
 120          * *                     * */
 121         /**
 122          * This method execute a task on the location on which the
 123          * process is running.
 124          *
 125          * @exception JniException if the binding mechanism fails.
 126          * @exception NativeException if the execution failed.
 127          */
 128         public void execute() throws JniException, NativeException {
 129                 MsgNative.taskExecute(this);
 130         }
 131         /**
 132          * This method cancels a task.
 133          *
 134          * @exception JniException if the binding mechanism fails.
 135          * @exception NativeException if the cancellation failed.
 136          */
 137         public void cancel() throws JniException, NativeException {
 138                 MsgNative.taskCancel(this);
 139         }
 140         /** Deletes a task.
 141          *
 142          * @exception                   JniException if the binding mechanism fails
 143          *                                              NativeException if the destruction failed.
 144          */
 145         protected void finalize() throws JniException, NativeException {
 146                 if (this.bind != 0)
 147                         MsgNative.taskDestroy(this);
 148         }
 149
 150         /**
 151          * Send the task on the mailbox identified by the specified name
 152          *
 153          * @exception  JniException if the binding mechanism fails.
 154          * @exception  NativeException if the retrieval fails.
 155          */
 156         public void send(String mailbox) throws JniException,NativeException {
 157                 MsgNative.taskSend(mailbox, this, -1);
 158         }
 159
 160         /**
 161          * Send the task on the mailbox identified by the specified name (wait at most \a timeout seconds)
 162          *
 163          * @exception  JniException if the binding mechanism fails.
 164          * @exception  NativeException if the retrieval fails.
 165          */
 166         public void send(String mailbox, double timeout) throws JniException,NativeException {
 167                 MsgNative.taskSend(mailbox, this, timeout);
 168         }
 169
 170         /**
 171          * Send the task on the mailbox identified by the specified alias  (capping the sending rate to \a maxrate)
 172          *
 173          * @exception  JniException if the binding mechanism fails.
 174          * @exception  NativeException if the retrieval fails.
 175          */
 176         public void sendBounded(String alias, double maxrate) throws JniException,NativeException {
 177                 MsgNative.taskSendBounded(alias, this, maxrate);
 178         }
 179
 180         /**
 181          * Retrieves next task from the mailbox identified by the specified name
 182          *
 183          * @exception  JniException if the binding mechanism fails.
 184          * @exception  NativeException if the retrieval fails.
 185          */
 186
 187         public static Task receive(String mailbox) throws JniException, NativeException {
 188                 return MsgNative.taskReceive(mailbox, -1.0, null);
 189         }
 190
 191         /**
 192          * Retrieves next task on the mailbox identified by the specified name (wait at most \a timeout seconds)
 193          *
 194          * @exception  JniException if the binding mechanism fails.
 195          * @exception  NativeException if the retrieval fails.
 196          */
 197         public static Task receive(String mailbox, double timeout) throws JniException, NativeException {
 198                 return MsgNative.taskReceive(mailbox, timeout, null);
 199         }
 200
 201         /**
 202          * Retrieves next task sent by a given host on the mailbox identified by the specified alias
 203          *
 204          * @exception  JniException if the binding mechanism fails.
 205          * @exception  NativeException if the retrieval fails.
 206          */
 207
 208         public static Task receive(String mailbox, Host host) throws JniException, NativeException {
 209                 return MsgNative.taskReceive(mailbox, -1.0, host);
 210         }
 211
 212         /**
 213          * Retrieves next task sent by a given host on the mailbox identified by the specified alias (wait at most \a timeout seconds)
 214          *
 215          * @exception  JniException if the binding mechanism fails.
 216          * @exception  NativeException if the retrieval fails.
 217          */
 218         public static Task receive(String mailbox, double timeout, Host host) throws JniException, NativeException {
 219                 return MsgNative.taskReceive(mailbox, timeout, host);
 220         }
 221
 222         /**
 223          * Test whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
 224          *
 225          * @exception  JniException if the binding mechanism fails.
 226          * @exception  NativeException if the retrieval fails.
 227          */
 228         public static int listenFrom(String mailbox) throws JniException, NativeException  {
 229                 return MsgNative.taskListenFrom(mailbox);
 230         }
 231         /**
 232          * Listen whether there is a waiting task on the mailbox identified by the specified alias
 233          *
 234          * @exception  JniException if the binding mechanism fails.
 235          * @exception  NativeException if the retrieval fails.
 236          */
 237         public static boolean listen(String mailbox) throws JniException, NativeException  {
 238                 return MsgNative.taskListen(mailbox);
 239         }
 240
 241         /**
 242          * 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.
 243          *
 244          * @exception  JniException if the binding mechanism fails.
 245          * @exception  NativeException if the retrieval fails.
 246          */
 247         public static int listenFromHost(String alias, Host host) throws JniException, NativeException  {
 248                 return MsgNative.taskListenFromHost(alias, host);
 249         }
 250 }