Logo AND Algorithmique Numérique Distribuée

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