Logo AND Algorithmique Numérique Distribuée

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