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  * Since most scheduling algorithms rely on a concept of
  16  * task that can be either computed locally or transferred
  17  * on another processor, it seems to be the right level of
  18  * abstraction for our purposes. A task may then be defined
  19  * by a computing amount, a message size and some private
  20  * data. To transfer a task you use an instance of the class
  21  * Channel identified by an number.
  22  *
  23  * @author  Abdelmalek Cherier
  24  * @author  Martin Quinson
  25  * @version 1.00, 07/05/01
  26  * @see Process
  27  * @see Channel
  28  * @since SimGrid 3.3
  29  * @since JDK1.5011
  30  */
  31 public class Task
  32 {
  33         /**
  34          * This attribute represents a bind between a java task object and
  35          * a native task. Even if this attribute is public you must never
  36          * access to it. It is set automaticatly during the build of the object.
  37          */
  38         public long bind = 0;
  39
  40         /**
  41          * Default constructor (disabled)
  42          */
  43         protected Task() {}
  44
  45         /**
  46          * Construct an new task with the specified processing amount and amount
  47          * of data needed.
  48          *
  49          * @param name                          The name of th task.
  50          *
  51          * @param computeDuration       A value of the processing amount (in flop) needed
  52          *                                                      to process the task. If 0, then it cannot be executed
  53          *                                                      with the execute() method. This value has to be >= 0.
  54          *
  55          * @param messageSize           A value of amount of data (in bytes) needed to transfert
  56          *                                                      this task. If 0, then it cannot be transfered this task.
  57          *                                                      If 0, then it cannot be transfered with the get() and put()
  58          *                                                      methods. This value has to be >= 0.
  59          *
  60          * @exception                           InvalidTaskNameException if the specified name is null.
  61          *                                                      InvalidComputeDuration if the specified compute duration is less than 0.
  62          *                                                      InvalidMessageSizeException if the specified message size is less than 0.
  63          */
  64         public Task(String name, double computeDuration, double messageSize) throws JniException {
  65
  66                 create(name,computeDuration,messageSize);
  67         }
  68
  69         /**
  70          * This method creates a new task with the specified features. The task
  71          * creation means that the native task is created and binded with the
  72          * java task instance. If the task is already created you must destroy it
  73          * before to use this method, otherwise the method throws the exception
  74          * TaskAlreadyCreatedException.
  75          *
  76          * @param name                          The name of the task.
  77          * @param computeDuration       A value of the processing amount (in flop) needed
  78          *                                                      to process the task. If 0, then it cannot be executed
  79          *                                                      with the execute() method. This value has to be >= 0.
  80          * @param messageSize           A value of amount of data (in bytes) needed to transfert
  81          *                                                      this task. If 0, then it cannot be transfered this task.
  82          *                                                      If 0, then it cannot be transfered with the get() and put()
  83          *                                                      methods. This value has to be >= 0.
  84          *
  85          * @exception                           InvalidTaskNameException if the specified name is null.
  86          *                                                      InvalidComputeDuration if the specified compute duration is less than 0.
  87          *                                                      InvalidMessageSizeException if the specified message size is less than 0.
  88          */
  89     public void create(String name, double computeDuration, double messageSize) throws JniException {
  90
  91         if(this.bind == 0)
  92             Msg.taskCreate(this,name,computeDuration,messageSize);
  93     }
  94
  95         /**
  96          * This method gets the sender of the task.
  97          *
  98          * @return                              The sender of the task.
  99          *
 100          * @exception                   InvalidTaskException is the specified task is not valid. A task
 101          *                                              is invalid if it is not binded with a native task.
 102          *
 103          */
 104         Process getSender() throws JniException{
 105                 return Msg.taskGetSender(this);
 106         }
 107
 108          /**
 109           * This method gets the source of the task.
 110           *
 111           * @return                             The source of the task.
 112           *
 113           * @exception                  InvalidTaskException is the specified task is not valid. A task
 114           *                                             is invalid if it is not binded with a native task.
 115           */
 116         public Host getSource()throws JniException, NativeException{
 117                 return Msg.taskGetSource(this);
 118         }
 119
 120         /**
 121          * This method gets the name of a task.
 122          *
 123          * @return                              The name of the task.
 124          *
 125          * @exception                   InvalidTaskException is the specified task is not valid. A task
 126          *                                              is invalid if it is not binded with a native task.
 127          */
 128         public String getName()throws JniException{
 129                 return Msg.taskGetName(this);
 130         }
 131
 132         /**
 133          * This method cancels a task.
 134          *
 135          * @exception                   InvalidTaskException if the specified task is not valid. A task
 136          *                                              is invalid if it is not binded with a native task.
 137          *                                              MsgException if the cancelation failed.
 138          */
 139         public void cancel() throws JniException, NativeException{
 140                 Msg.taskCancel(this);
 141         }
 142
 143         /**
 144          * This method gets the computing amount of the task.
 145          *
 146          * @return                              The computing amount of the task.
 147          *
 148          * @exception                   InvalidTaskException is the specified task is not valid. A task
 149          *                                              is invalid if it is not binded with a native task.
 150          */
 151         public double getComputeDuration()throws JniException{
 152                 return Msg.taskGetComputeDuration(this);
 153         }
 154
 155         /**
 156          * This method gets the remaining computation.
 157          *
 158          * @return                              The remaining duration.
 159          *
 160          * @exception                   InvalidTaskException is the specified task is not valid. A task
 161          *                                              is invalid if it is not binded with a native task.
 162          */
 163         public double getRemainingDuration() throws JniException {
 164                 return Msg.taskGetRemainingDuration(this);
 165         }
 166
 167         /**
 168          * This method sets the priority of the computation of the task.
 169          * The priority doesn't affect the transfert rate. For example a
 170          * priority of 2 will make the task receive two times more cpu than
 171          * the other ones.
 172          *
 173          * @param                               The new priority of the task.
 174          *
 175          * @exception                   InvalidTaskException is the specified task is not valid. A task
 176          *                                              is invalid if it is not binded with a native task.
 177          */
 178         public void setPrirority(double priority) throws JniException {
 179                  Msg.taskSetPriority(this,priority);
 180         }
 181
 182         /**
 183          * This method destroys a task.
 184          *
 185          * @exception                   InvalidTaskException is the specified task is not valid. A task
 186          *                                              is invalid if it is not binded with a native task.
 187          *                                              MsgException if the destruction failed.
 188          */
 189         public void destroy()  throws JniException, NativeException {
 190                 if(this.bind != 0) {
 191                         Msg.taskDestroy(this);
 192                         this.bind = 0;
 193                 }
 194         }
 195
 196         /**
 197          * This method deletes a task.
 198          *
 199          * @exception                   InvalidTaskException is the specified task is not valid. A task
 200          *                                              is invalid if it is not binded with a native task.
 201          *                                              MsgException if the destruction failed.
 202          */
 203         protected void finalize() throws JniException, NativeException {
 204                 if(this.bind != 0)
 205                         Msg.taskDestroy(this);
 206         }
 207
 208         /**
 209          * This method execute a task on the location on which the
 210          * process is running.
 211          *
 212          * @exception                   InvalidTaskException is the specified task is not valid. A task
 213          *                                              is invalid if it is not binded with a native task.
 214          *                                              MsgException if the destruction failed.
 215          */
 216         public void execute() throws JniException, NativeException {
 217                 Msg.taskExecute(this);
 218         }
 219 }