Logo AND Algorithmique Numérique Distribuée

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