1 /* Copyright (c) 2006-2020. The SimGrid Team. All rights reserved. */
3 /* This program is free software; you can redistribute it and/or modify it
4 * under the terms of the license (GNU LGPL) which comes with this package. */
6 package org.simgrid.msg;
9 * A task is either something to compute somewhere, or something to exchange between two hosts (or both).
10 * It is defined by a computing amount and a message size.
15 * This attribute represents a bind between a java task object and
16 * a native task. Even if this attribute is public you must never
17 * access to it. It is set automatically during the build of the object.
19 private long bind = 0;
23 protected String name;
25 private double messageSize;
27 /** Default constructor (all fields to 0 or null) */
37 * Construct a new task with the specified processing amount and amount
40 * @param name Task's name
42 * @param flopsAmount 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.
46 * @param bytesAmount A value of amount of data (in bytes) needed to transfert this task.
47 * If 0, then it cannot be transferred with the get() and put() methods.
48 * This value has to be ≥ 0.
50 public Task(String name, double flopsAmount, double bytesAmount) {
52 throw new IllegalArgumentException("Task flopsAmount (" + flopsAmount + ") cannot be negative");
54 throw new IllegalArgumentException("Task bytesAmount (" + bytesAmount + ") cannot be negative");
56 create(name, flopsAmount, bytesAmount);
59 this.messageSize = bytesAmount;
62 * Construct a new parallel task with the specified processing amount and amount for each host
65 * @param name The name of the parallel task.
66 * @param hosts The list of hosts implied by the parallel task.
67 * @param flopsAmount The amount of operations to be performed by each host of hosts.
68 * flopsAmount[i] is the total number of operations that have to be
69 * performed on hosts[i].
70 * @param bytesAmount A matrix describing the amount of data to exchange between hosts. The
71 * length of this array must be hosts.length * hosts.length. It is actually
72 * used as a matrix with the lines being the source and the columns being
73 * the destination of the communications.
75 public Task(String name, Host[]hosts, double[]flopsAmount, double[]bytesAmount) {
76 if (flopsAmount == null)
77 throw new IllegalArgumentException("Parallel task flops amounts is null");
78 if (bytesAmount == null)
79 throw new IllegalArgumentException("Parallel task bytes amounts is null");
81 throw new IllegalArgumentException("Host list is null");
83 throw new IllegalArgumentException("Parallel task name is null");
85 parallelCreate(name, hosts, flopsAmount, bytesAmount);
90 * The natively implemented method to create a MSG task.
92 * @param name The name of the task.
93 * @param flopsAmount A value of the processing amount (in flop) needed
94 * to process the task. If 0, then it cannot be executed
95 * with the execute() method. This value has to be >= 0.
96 * @param bytesAmount A value of amount of data (in bytes) needed to transfert
97 * this task. If 0, then it cannot be transferred this task.
98 * If 0, then it cannot be transferred with the get() and put()
99 * methods. This value has to be >= 0.
100 * @exception IllegalArgumentException if compute duration <0 or message size <0
102 private final native void create(String name,
106 * The natively implemented method to create a MSG parallel task.
108 * @param name The name of the parallel task.
109 * @param hosts The list of hosts implied by the parallel task.
110 * @param flopsAmount The total number of operations that have to be performed
112 * @param bytesAmount An array of doubles
115 private final native void parallelCreate(String name,
118 double[]bytesAmount);
120 * * Getters / Setters * *
122 /** Gets the name of the task */
123 public String getName() {
127 /** Gets the sender of the task (or null if not sent yet) */
128 public native Process getSender();
130 /** Gets the source of the task (or null if not sent yet). */
131 public native Host getSource();
133 /** Gets the remaining amount of flops to execute in this task
135 * If it's ongoing, you get the exact amount at the present time. If it's already done, it's 0.
137 public native double getFlopsAmount();
139 * Sets the name of the task
140 * @param name the new task name
142 public native void setName(String name);
144 * This method sets the priority of the computation of the task.
145 * The priority doesn't affect the transfer rate. For example a
146 * priority of 2 will make the task receive two times more cpu than
149 * @param priority The new priority of the task.
151 public native void setPriority(double priority);
153 /** Set the computation amount needed to process the task
155 * Warning if the execution is already started and ongoing, this call does nothing.
156 * @param flopsAmount the amount of computation needed to process the task
158 public native void setFlopsAmount(double flopsAmount);
160 * Set the amount of bytes to exchange the task
162 * Warning if the communication is already started and ongoing, this call does nothing.
163 * @param bytesAmount the size of the task
165 public native void setBytesAmount(double bytesAmount);
167 * * Computation-related * *
170 * Executes a task on the location on which the current process is running.
172 * @throws HostFailureException
173 * @throws TaskCancelledException
175 public native void execute() throws HostFailureException,TaskCancelledException;
177 /** Changes the maximum CPU utilization of a computation task. Unit is flops/s. */
178 public native void setBound(double bound);
180 /** Cancels a task. */
181 public native void cancel();
184 * Deletes a task once the garbage collector reclaims it
185 * @deprecated (from Java9 onwards)
187 @Deprecated @Override
188 protected void finalize() throws Throwable{
190 bind=0; // to avoid segfaults if the impossible happens yet again making this task surviving its finalize()
192 protected native void nativeFinalize();
194 * * Communication-related * *
197 /** Send the task asynchronously on the specified mailbox,
198 * with no way to retrieve whether the communication succeeded or not
201 public native void dsendBounded(String mailbox, double maxrate);
204 /** Send the task asynchronously on the specified mailbox,
205 * with no way to retrieve whether the communication succeeded or not
208 public native void dsend(String mailbox);
211 * Sends the task on the specified mailbox
213 * @param mailbox where to send the message
214 * @throws TimeoutException
215 * @throws HostFailureException
216 * @throws TransferFailureException
218 public void send(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
223 * Sends the task on the specified mailbox (wait at most \a timeout seconds)
225 * @param mailbox where to send the message
227 * @throws TimeoutException
228 * @throws HostFailureException
229 * @throws TransferFailureException
231 public void send(String mailbox, double timeout) throws TransferFailureException, HostFailureException, TimeoutException {
232 sendBounded(mailbox, timeout, -1);
235 /** Sends the task on the specified mailbox (capping the sending rate to \a maxrate)
237 * @param mailbox where to send the message
239 * @throws TransferFailureException
240 * @throws HostFailureException
241 * @throws TimeoutException
243 public void sendBounded(String mailbox, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException {
244 sendBounded(mailbox, -1, maxrate);
248 /** Sends the task on the specified mailbox (capping the sending rate to \a maxrate) with a timeout
250 * @param mailbox where to send the message
253 * @throws TransferFailureException
254 * @throws HostFailureException
255 * @throws TimeoutException
257 public native void sendBounded(String mailbox, double timeout, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException;
261 * Sends the task on the mailbox asynchronously
263 public native Comm isend(String mailbox);
266 * Sends the task on the mailbox asynchronously (capping the sending rate to \a maxrate)
268 public native Comm isendBounded(String mailbox, double maxrate);
272 * Starts listening for receiving a task from an asynchronous communication
274 * @return a Comm handler
276 public static native Comm irecv(String mailbox);
279 * Retrieves next task on the mailbox identified by the specified alias
285 public static Task receive(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
286 return receive(mailbox, -1.0);
290 * Retrieves next task on the mailbox identified by the specified alias (wait at most \a timeout seconds)
296 public static native Task receive(String mailbox, double timeout) throws TransferFailureException, HostFailureException, TimeoutException;
299 * Starts listening for receiving a task from an asynchronous communication with a capped rate
301 * @return a Comm handler
303 public static native Comm irecvBounded(String mailbox, double rate);
305 * Retrieves next task from the mailbox identified by the specified name with a capped rate
311 public static Task receiveBounded(String mailbox, double rate) throws TransferFailureException, HostFailureException, TimeoutException {
312 return receiveBounded(mailbox, -1.0, rate);
316 * Retrieves next task on the mailbox identified by the specified name (wait at most \a timeout seconds) with a capped rate
322 public static native Task receiveBounded(String mailbox, double timeout, double rate) throws TransferFailureException, HostFailureException, TimeoutException;
327 * Tests whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
329 public static native int listenFrom(String mailbox);
331 * Listen whether there is a task waiting (either for a send or a recv) on the mailbox identified by the specified alias
333 public static native boolean listen(String mailbox);
336 * Class initializer, to initialize various JNI stuff
338 public static native void nativeInit();
340 org.simgrid.NativeLib.nativeInit();
344 public double getMessageSize() {
345 return this.messageSize;