docs/source/java/org/simgrid/msg/Task.rst

   1 class org.simgrid.msg.Task
   2 ==========================
   3
   4 .. java:package:: org.simgrid.msg
   5    :noindex:
   6
   7 .. java:type:: public class Task
   8
   9    A task is either something to compute somewhere, or something to exchange between two hosts (or both). It is defined by a computing amount and a message size.
  10
  11 Fields
  12 ------
  13 name
  14 ^^^^
  15
  16 .. java:field:: protected String name
  17    :outertype: Task
  18
  19    Task name
  20
  21 Constructors
  22 ------------
  23 Task
  24 ^^^^
  25
  26 .. java:constructor:: public Task()
  27    :outertype: Task
  28
  29    Default constructor (all fields to 0 or null)
  30
  31 Task
  32 ^^^^
  33
  34 .. java:constructor:: public Task(String name, double flopsAmount, double bytesAmount)
  35    :outertype: Task
  36
  37    Construct a new task with the specified processing amount and amount of data needed.
  38
  39    :param name: Task's name
  40    :param flopsAmount: A value of the processing amount (in flop) needed to process the task. If 0, then it cannot be executed with the execute() method. This value has to be ≥ 0.
  41    :param bytesAmount: A value of amount of data (in bytes) needed to transfert this task. If 0, then it cannot be transferred with the get() and put() methods. This value has to be ≥ 0.
  42
  43 Task
  44 ^^^^
  45
  46 .. java:constructor:: public Task(String name, Host[] hosts, double[] flopsAmount, double[] bytesAmount)
  47    :outertype: Task
  48
  49    Construct a new parallel task with the specified processing amount and amount for each host implied.
  50
  51    :param name: The name of the parallel task.
  52    :param hosts: The list of hosts implied by the parallel task.
  53    :param flopsAmount: The amount of operations to be performed by each host of hosts. flopsAmount[i] is the total number of operations that have to be performed on hosts[i].
  54    :param bytesAmount: A matrix describing the amount of data to exchange between hosts. The length of this array must be hosts.length * hosts.length. It is actually used as a matrix with the lines being the source and the columns being the destination of the communications.
  55
  56 Methods
  57 -------
  58 cancel
  59 ^^^^^^
  60
  61 .. java:method:: public native void cancel()
  62    :outertype: Task
  63
  64    Cancels a task.
  65
  66 dsend
  67 ^^^^^
  68
  69 .. java:method:: public native void dsend(String mailbox)
  70    :outertype: Task
  71
  72    Send the task asynchronously on the specified mailbox, with no way to retrieve whether the communication succeeded or not
  73
  74 dsendBounded
  75 ^^^^^^^^^^^^
  76
  77 .. java:method:: public native void dsendBounded(String mailbox, double maxrate)
  78    :outertype: Task
  79
  80    Send the task asynchronously on the specified mailbox, with no way to retrieve whether the communication succeeded or not
  81
  82 execute
  83 ^^^^^^^
  84
  85 .. java:method:: public native void execute() throws HostFailureException, TaskCancelledException
  86    :outertype: Task
  87
  88    Executes a task on the location on which the current process is running.
  89
  90    :throws HostFailureException:
  91    :throws TaskCancelledException:
  92
  93 finalize
  94 ^^^^^^^^
  95
  96 .. java:method:: @Deprecated @Override protected void finalize() throws Throwable
  97    :outertype: Task
  98
  99    Deletes a task once the garbage collector reclaims it
 100
 101 getFlopsAmount
 102 ^^^^^^^^^^^^^^
 103
 104 .. java:method:: public native double getFlopsAmount()
 105    :outertype: Task
 106
 107    Gets the remaining amount of flops to execute in this task If it's ongoing, you get the exact amount at the present time. If it's already done, it's 0.
 108
 109 getMessageSize
 110 ^^^^^^^^^^^^^^
 111
 112 .. java:method:: public double getMessageSize()
 113    :outertype: Task
 114
 115 getName
 116 ^^^^^^^
 117
 118 .. java:method:: public String getName()
 119    :outertype: Task
 120
 121    Gets the name of the task
 122
 123 getSender
 124 ^^^^^^^^^
 125
 126 .. java:method:: public native Process getSender()
 127    :outertype: Task
 128
 129    Gets the sender of the task (or null if not sent yet)
 130
 131 getSource
 132 ^^^^^^^^^
 133
 134 .. java:method:: public native Host getSource()
 135    :outertype: Task
 136
 137    Gets the source of the task (or null if not sent yet).
 138
 139 irecv
 140 ^^^^^
 141
 142 .. java:method:: public static native Comm irecv(String mailbox)
 143    :outertype: Task
 144
 145    Starts listening for receiving a task from an asynchronous communication
 146
 147    :param mailbox:
 148    :return: a Comm handler
 149
 150 irecvBounded
 151 ^^^^^^^^^^^^
 152
 153 .. java:method:: public static native Comm irecvBounded(String mailbox, double rate)
 154    :outertype: Task
 155
 156    Starts listening for receiving a task from an asynchronous communication with a capped rate
 157
 158    :param mailbox:
 159    :return: a Comm handler
 160
 161 isend
 162 ^^^^^
 163
 164 .. java:method:: public native Comm isend(String mailbox)
 165    :outertype: Task
 166
 167    Sends the task on the mailbox asynchronously
 168
 169 isendBounded
 170 ^^^^^^^^^^^^
 171
 172 .. java:method:: public native Comm isendBounded(String mailbox, double maxrate)
 173    :outertype: Task
 174
 175    Sends the task on the mailbox asynchronously (capping the sending rate to \a maxrate)
 176
 177 listen
 178 ^^^^^^
 179
 180 .. java:method:: public static native boolean listen(String mailbox)
 181    :outertype: Task
 182
 183    Listen whether there is a task waiting (either for a send or a recv) on the mailbox identified by the specified alias
 184
 185 listenFrom
 186 ^^^^^^^^^^
 187
 188 .. java:method:: public static native int listenFrom(String mailbox)
 189    :outertype: Task
 190
 191    Tests whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
 192
 193 nativeFinalize
 194 ^^^^^^^^^^^^^^
 195
 196 .. java:method:: protected native void nativeFinalize()
 197    :outertype: Task
 198
 199 nativeInit
 200 ^^^^^^^^^^
 201
 202 .. java:method:: public static native void nativeInit()
 203    :outertype: Task
 204
 205    Class initializer, to initialize various JNI stuff
 206
 207 receive
 208 ^^^^^^^
 209
 210 .. java:method:: public static Task receive(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException
 211    :outertype: Task
 212
 213    Retrieves next task on the mailbox identified by the specified alias
 214
 215    :param mailbox:
 216    :return: a Task
 217
 218 receive
 219 ^^^^^^^
 220
 221 .. java:method:: public static native Task receive(String mailbox, double timeout) throws TransferFailureException, HostFailureException, TimeoutException
 222    :outertype: Task
 223
 224    Retrieves next task on the mailbox identified by the specified alias (wait at most \a timeout seconds)
 225
 226    :param mailbox:
 227    :param timeout:
 228    :return: a Task
 229
 230 receiveBounded
 231 ^^^^^^^^^^^^^^
 232
 233 .. java:method:: public static Task receiveBounded(String mailbox, double rate) throws TransferFailureException, HostFailureException, TimeoutException
 234    :outertype: Task
 235
 236    Retrieves next task from the mailbox identified by the specified name with a capped rate
 237
 238    :param mailbox:
 239    :return: a Task
 240
 241 receiveBounded
 242 ^^^^^^^^^^^^^^
 243
 244 .. java:method:: public static native Task receiveBounded(String mailbox, double timeout, double rate) throws TransferFailureException, HostFailureException, TimeoutException
 245    :outertype: Task
 246
 247    Retrieves next task on the mailbox identified by the specified name (wait at most \a timeout seconds) with a capped rate
 248
 249    :param mailbox:
 250    :param timeout:
 251    :return: a Task
 252
 253 send
 254 ^^^^
 255
 256 .. java:method:: public void send(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException
 257    :outertype: Task
 258
 259    Sends the task on the specified mailbox
 260
 261    :param mailbox: where to send the message
 262    :throws TimeoutException:
 263    :throws HostFailureException:
 264    :throws TransferFailureException:
 265
 266 send
 267 ^^^^
 268
 269 .. java:method:: public void send(String mailbox, double timeout) throws TransferFailureException, HostFailureException, TimeoutException
 270    :outertype: Task
 271
 272    Sends the task on the specified mailbox (wait at most \a timeout seconds)
 273
 274    :param mailbox: where to send the message
 275    :param timeout:
 276    :throws TimeoutException:
 277    :throws HostFailureException:
 278    :throws TransferFailureException:
 279
 280 sendBounded
 281 ^^^^^^^^^^^
 282
 283 .. java:method:: public void sendBounded(String mailbox, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException
 284    :outertype: Task
 285
 286    Sends the task on the specified mailbox (capping the sending rate to \a maxrate)
 287
 288    :param mailbox: where to send the message
 289    :param maxrate:
 290    :throws TransferFailureException:
 291    :throws HostFailureException:
 292    :throws TimeoutException:
 293
 294 sendBounded
 295 ^^^^^^^^^^^
 296
 297 .. java:method:: public native void sendBounded(String mailbox, double timeout, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException
 298    :outertype: Task
 299
 300    Sends the task on the specified mailbox (capping the sending rate to \a maxrate) with a timeout
 301
 302    :param mailbox: where to send the message
 303    :param timeout:
 304    :param maxrate:
 305    :throws TransferFailureException:
 306    :throws HostFailureException:
 307    :throws TimeoutException:
 308
 309 setBound
 310 ^^^^^^^^
 311
 312 .. java:method:: public native void setBound(double bound)
 313    :outertype: Task
 314
 315    Changes the maximum CPU utilization of a computation task. Unit is flops/s.
 316
 317 setBytesAmount
 318 ^^^^^^^^^^^^^^
 319
 320 .. java:method:: public native void setBytesAmount(double bytesAmount)
 321    :outertype: Task
 322
 323    Set the amount of bytes to exchange the task Warning if the communication is already started and ongoing, this call does nothing.
 324
 325    :param bytesAmount: the size of the task
 326
 327 setFlopsAmount
 328 ^^^^^^^^^^^^^^
 329
 330 .. java:method:: public native void setFlopsAmount(double flopsAmount)
 331    :outertype: Task
 332
 333    Set the computation amount needed to process the task Warning if the execution is already started and ongoing, this call does nothing.
 334
 335    :param flopsAmount: the amount of computation needed to process the task
 336
 337 setName
 338 ^^^^^^^
 339
 340 .. java:method:: public native void setName(String name)
 341    :outertype: Task
 342
 343    Sets the name of the task
 344
 345    :param name: the new task name
 346
 347 setPriority
 348 ^^^^^^^^^^^
 349
 350 .. java:method:: public native void setPriority(double priority)
 351    :outertype: Task
 352
 353    This method sets the priority of the computation of the task. The priority doesn't affect the transfer rate. For example a priority of 2 will make the task receive two times more cpu than the other ones.
 354
 355    :param priority: The new priority of the task.
 356