Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
7cd0d8705b1b7f68132831c59bec895f7441daaa
[simgrid.git] / org / simgrid / msg / Task.java
1 /*
2  * Copyright 2006-2012 The SimGrid Team.           
3  * All right reserved. 
4  *
5  * This program is free software; you can redistribute 
6  * it and/or modify it under the terms of the license 
7  * (GNU LGPL) which comes with this package.
8  */
9
10 package org.simgrid.msg;
11
12 /**
13  * A task is either something to compute somewhere, or something to exchange between two hosts (or both).
14  * It is defined by a computing amount and a message size.
15  *
16  */
17 public class Task {
18         /**
19          * This attribute represents a bind between a java task object and
20          * a native task. Even if this attribute is public you must never
21          * access to it. It is set automatically during the build of the object.
22          */
23         private long bind = 0;
24         /**
25          * Task name
26          */
27         protected String name;
28
29         private double messageSize;
30
31         static private Long idCpt = 0L;
32
33         private Long id;
34
35         /** Default constructor (all fields to 0 or null) */
36         public Task() {
37                 create(null, 0, 0);
38                 this.messageSize = 0;
39                 setId(idCpt);
40                 idCpt++;
41         }
42
43         /* *              * *
44          * * Constructors * *
45          * *              * */
46         /**
47          * Construct an new task with the specified processing amount and amount
48          * of data needed.
49          *
50          * @param name  Task's name
51          *
52          * @param computeDuration       A value of the processing amount (in flop) needed to process the task. 
53          *                              If 0, then it cannot be executed with the execute() method.
54          *                              This value has to be >= 0.
55          *
56          * @param messageSize           A value of amount of data (in bytes) needed to transfert this task.
57          *                              If 0, then it cannot be transfered with the get() and put() methods.
58          *                              This value has to be >= 0.
59          */ 
60         public Task(String name, double computeDuration, double messageSize) {
61                 create(name, computeDuration, messageSize);
62                 this.messageSize = messageSize;
63                 setId(idCpt);
64                 idCpt++;
65         }
66         /**
67          * Construct an new parallel task with the specified processing amount and amount for each host
68          * implied.
69          *
70          * @param name          The name of the parallel task.
71          * @param hosts         The list of hosts implied by the parallel task.
72          * @param computeDurations      The amount of operations to be performed by each host of \a hosts.
73          * @param messageSizes  A matrix describing the amount of data to exchange between hosts.
74          */ 
75         public Task(String name, Host[]hosts, double[]computeDurations, double[]messageSizes) {
76                 parallelCreate(name, hosts, computeDurations, messageSizes);
77         }
78         
79         /**
80          * The natively implemented method to create a MSG task.
81          *
82          * @param name            The name of th task.
83          * @param computeDuration    A value of the processing amount (in flop) needed 
84          *                        to process the task. If 0, then it cannot be executed
85          *                        with the execute() method. This value has to be >= 0.
86          * @param messageSize        A value of amount of data (in bytes) needed to transfert 
87          *                        this task. If 0, then it cannot be transfered this task. 
88          *                        If 0, then it cannot be transfered with the get() and put() 
89          *                        methods. This value has to be >= 0.
90          * @exception             IllegalArgumentException if compute duration <0 or message size <0
91          */
92         private final native void create(String name,
93                         double computeDuration,
94                         double messageSize)
95         throws IllegalArgumentException;                
96         /**
97          * The natively implemented method to create a MSG parallel task.
98          *
99          * @param name                The name of the parallel task.
100          * @param hosts                The list of hosts implied by the parallel task.
101          * @param computeDurations    The total number of operations that have to be performed
102          *                            on the hosts.
103          * @param messageSizes        An array of doubles
104          *
105          */
106         private final native void parallelCreate(String name,
107                         Host[]hosts,
108                         double[]computeDurations,
109                         double[]messageSizes)
110         throws NullPointerException, IllegalArgumentException;
111         /* *                   * *
112          * * Getters / Setters * *
113          * *                   * */
114     /** 
115      * Gets the name of a task
116      */
117         public String getName() {
118                 return name;
119         }
120         /**
121          * Gets the sender of the task 
122          * Returns null if the task hasn't been sent yet
123          */
124         public native Process getSender();
125         /** Gets the source of the task.
126          * Returns null if the task hasn't been sent yet.
127      */
128         public native Host getSource();   
129         /** Gets the computing amount of the task
130      * FIXME: Cache it !
131      */
132         public native double getComputeDuration();
133         /** Gets the remaining computation of the task
134      */
135         public native double getRemainingDuration();
136         /**
137          * Sets the name of the task
138          * @param name the new task name.c
139          */
140         public native void setName(String name);
141         /**
142          * This method sets the priority of the computation of the task.
143          * The priority doesn't affect the transfer rate. For example a
144          * priority of 2 will make the task receive two times more cpu than
145          * the other ones.
146          *
147          * @param priority      The new priority of the task.
148          */ 
149         public native void setPriority(double priority);
150         /**
151          * Set the computation amount needed to process the task
152          * @param computationAmount the amount of computation needed to process the task
153          */
154         public native void setComputeDuration(double computationAmount);
155         /* *                     * *
156          * * Computation-related * *
157          * *                     * */
158         /**
159          * Executes a task on the location on which the process is running.
160          *
161      *
162      * @throws HostFailureException
163      * @throws TaskCancelledException
164      */
165         public native void execute() throws HostFailureException,TaskCancelledException;
166         /**
167          * Cancels a task.
168          *
169          */ 
170         public native void cancel();
171         /** Deletes a task.
172          *
173          * @exception                   NativeException if the destruction failed.
174          */ 
175         protected void finalize() throws NativeException {
176                 destroy();
177         }
178         /**
179          * The natively implemented method to destroy a MSG task.
180          */
181         protected native void destroy();
182         /* *                       * *
183          * * Communication-related * *
184          * *                       * */
185
186         /** Send the task asynchronously on the mailbox identified by the specified name, 
187          *  with no way to retrieve whether the communication succeeded or not
188          * 
189          */
190         public native void dsend(String mailbox);       
191         /**
192          * Sends the task on the mailbox identified by the specified name 
193          *
194      * @param mailbox
195      * @throws TimeoutException
196          * @throws HostFailureException 
197          * @throws TransferFailureException 
198          */
199         public void send(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
200                 send(mailbox, -1);
201         } 
202
203         /**
204          * Sends the task on the mailbox identified by the specified name (wait at most \a timeout seconds)
205          *
206      * @param mailbox
207      * @param timeout
208      * @exception  NativeException if the retrieval fails.
209          * @throws TimeoutException 
210          * @throws HostFailureException 
211          * @throws TransferFailureException 
212          */
213         public native void send(String mailbox, double timeout) throws TransferFailureException, HostFailureException, TimeoutException;
214         /**
215          * Sends the task on the mailbox identified by the specified alias  (capping the sending rate to \a maxrate) 
216          *
217      * @param alias
218      * @param maxrate 
219      * @throws TransferFailureException
220      * @throws HostFailureException
221      * @throws TimeoutException
222          */
223         public native void sendBounded(String alias, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException;
224         /**
225          * Sends the task on the mailbox asynchronously
226          */
227         public native Comm isend(String mailbox);
228
229         /**
230          * Sends the task on the mailbox asynchronously (capping the sending rate to \a maxrate)
231          */
232         public native Comm isendBounded(String mailbox, double maxrate);
233         
234
235         /**
236          * Starts listening for receiving a task from an asynchronous communication
237          * @param mailbox
238          */
239         public static native Comm irecv(String mailbox);
240         /**
241          * Retrieves next task from the mailbox identified by the specified name
242          *
243      * @param mailbox
244          */
245
246         public static Task receive(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
247                 return receive(mailbox, -1.0, null);
248         }
249
250         /**
251          * Retrieves next task on the mailbox identified by the specified name (wait at most \a timeout seconds)
252          *
253      * @param mailbox
254      * @param timeout
255          */
256         public static Task receive(String mailbox, double timeout) throws  TransferFailureException, HostFailureException, TimeoutException {
257                 return receive(mailbox, timeout, null);
258         }
259
260         /**
261          * Retrieves next task sent by a given host on the mailbox identified by the specified alias 
262          *
263      * @param mailbox
264      * @param host
265          */
266
267         public static Task receive(String mailbox, Host host) throws TransferFailureException, HostFailureException, TimeoutException {
268                 return receive(mailbox, -1.0, host);
269         }
270
271         /**
272          * Retrieves next task sent by a given host on the mailbox identified by the specified alias (wait at most \a timeout seconds)
273          *
274      * @param mailbox
275      * @param timeout 
276      * @param host
277          */
278         public native static Task receive(String mailbox, double timeout, Host host) throws TransferFailureException, HostFailureException, TimeoutException;
279         /**
280          * Tests whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
281      */
282         public native static int listenFrom(String mailbox);
283         /**
284          * Listen whether there is a waiting task on the mailbox identified by the specified alias
285      */
286         public native static boolean listen(String mailbox);
287
288         /**
289          * 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.
290      */
291         public native static int listenFromHost(String alias, Host host);
292         
293         /**
294          * Class initializer, to initialize various JNI stuff
295          */
296         public static native void nativeInit();
297         static {
298                 Msg.nativeInit();
299                 nativeInit();
300         }
301
302         public double getMessageSize() {
303                 return this.messageSize;
304         }
305
306         public Long getId() {
307                 return id;
308         }
309
310         public void setId(Long id) {
311                 this.id = id;
312         }
313 }