Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
84eaf886ad1170b17cf07aef2d69441f3c6b9aff
[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         /** Default constructor (all fields to 0 or null) */
30         public Task() {
31                 create(null, 0, 0);
32         }
33
34         /* *              * *
35          * * Constructors * *
36          * *              * */
37         /**
38          * Construct an new task with the specified processing amount and amount
39          * of data needed.
40          *
41          * @param name  Task's name
42          *
43          * @param computeDuration       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 messageSize           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 computeDuration, double messageSize) {
52                 create(name, computeDuration, messageSize);
53         }
54         /**
55          * Construct an new parallel task with the specified processing amount and amount for each host
56          * implied.
57          *
58          * @param name          The name of the parallel task.
59          * @param hosts         The list of hosts implied by the parallel task.
60          * @param computeDurations      The amount of operations to be performed by each host of \a hosts.
61          * @param messageSizes  A matrix describing the amount of data to exchange between hosts.
62          */ 
63         public Task(String name, Host[]hosts, double[]computeDurations, double[]messageSizes) {
64                 parallelCreate(name, hosts, computeDurations, messageSizes);
65         }
66         
67         /**
68          * The natively implemented method to create a MSG task.
69          *
70          * @param name            The name of th task.
71          * @param computeDuration    A value of the processing amount (in flop) needed 
72          *                        to process the task. If 0, then it cannot be executed
73          *                        with the execute() method. This value has to be >= 0.
74          * @param messageSize        A value of amount of data (in bytes) needed to transfert 
75          *                        this task. If 0, then it cannot be transfered this task. 
76          *                        If 0, then it cannot be transfered with the get() and put() 
77          *                        methods. This value has to be >= 0.
78          * @exception             IllegalArgumentException if compute duration <0 or message size <0
79          */
80         final native void create(String name,
81                         double computeDuration,
82                         double messageSize)
83         throws IllegalArgumentException;                
84         /**
85          * The natively implemented method to create a MSG parallel task.
86          *
87          * @param name                The name of the parallel task.
88          * @param hosts                The list of hosts implied by the parallel task.
89          * @param computeDurations    The total number of operations that have to be performed
90          *                            on the hosts.
91          * @param messageSizes        An array of doubles
92          *
93          */
94         final native void parallelCreate(String name,
95                         Host[]hosts,
96                         double[]computeDurations,
97                         double[]messageSizes)
98         throws NullPointerException, IllegalArgumentException;
99         /* *                   * *
100          * * Getters / Setters * *
101          * *                   * */
102     /** 
103      * Gets the name of a task
104      */
105         public String getName() {
106                 return name;
107         }
108         /**
109          * Gets the sender of the task 
110          * Returns null if the task hasn't been sent yet
111          */
112         public native Process getSender();
113         /** Gets the source of the task.
114          * Returns null if the task hasn't been sent yet.
115      */
116         public native Host getSource();   
117         /** Gets the computing amount of the task
118      * FIXME: Cache it !
119      */
120         public native double getComputeDuration();
121         /** Gets the remaining computation of the task
122      */
123         public native double getRemainingDuration();
124         /**
125          * Sets the name of the task
126          * @param name the new task name.c
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          * @param computationAmount the amount of computation needed to process the task
141          */
142         public native void setComputeDuration(double computationAmount);
143         /* *                     * *
144          * * Computation-related * *
145          * *                     * */
146         /**
147          * Executes a task on the location on which the process is running.
148          *
149      *
150      * @throws HostFailureException
151      * @throws TaskCancelledException
152      */
153         public native void execute() throws HostFailureException,TaskCancelledException;
154         /**
155          * Cancels a task.
156          *
157          */ 
158         public native void cancel();
159         /** Deletes a task.
160          *
161          * @exception                   NativeException if the destruction failed.
162          */ 
163         protected void finalize() throws NativeException {
164                 destroy();
165         }
166         /**
167          * The natively implemented method to destroy a MSG task.
168          */
169         protected native void destroy();
170         /* *                       * *
171          * * Communication-related * *
172          * *                       * */
173
174         /** Send the task asynchronously on the mailbox identified by the specified name, 
175          *  with no way to retrieve whether the communication succeeded or not
176          * 
177          */
178         public native void dsend(String mailbox);       
179         /**
180          * Sends the task on the mailbox identified by the specified name 
181          *
182      * @param mailbox
183      * @throws TimeoutException
184          * @throws HostFailureException 
185          * @throws TransferFailureException 
186          */
187         public void send(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
188                 send(mailbox, -1);
189         } 
190
191         /**
192          * Sends the task on the mailbox identified by the specified name (wait at most \a timeout seconds)
193          *
194      * @param mailbox
195      * @param timeout
196      * @exception  NativeException if the retrieval fails.
197          * @throws TimeoutException 
198          * @throws HostFailureException 
199          * @throws TransferFailureException 
200          */
201         public native void send(String mailbox, double timeout) throws TransferFailureException, HostFailureException, TimeoutException;
202         /**
203          * Sends the task on the mailbox identified by the specified alias  (capping the sending rate to \a maxrate) 
204          *
205      * @param alias
206      * @param maxrate 
207      * @throws TransferFailureException
208      * @throws HostFailureException
209      * @throws TimeoutException
210          */
211         public native void sendBounded(String alias, double maxrate) throws TransferFailureException, HostFailureException, TimeoutException;
212         /**
213          * Sends the task on the mailbox asynchronously
214          */
215         public native Comm isend(String mailbox);
216         
217         /**
218          * Starts listening for receiving a task from an asynchronous communication
219          * @param mailbox
220          */
221         public static native Comm irecv(String mailbox);
222         /**
223          * Retrieves next task from the mailbox identified by the specified name
224          *
225      * @param mailbox
226          */
227
228         public static Task receive(String mailbox) throws TransferFailureException, HostFailureException, TimeoutException {
229                 return receive(mailbox, -1.0, null);
230         }
231
232         /**
233          * Retrieves next task on the mailbox identified by the specified name (wait at most \a timeout seconds)
234          *
235      * @param mailbox
236      * @param timeout
237          */
238         public static Task receive(String mailbox, double timeout) throws  TransferFailureException, HostFailureException, TimeoutException {
239                 return receive(mailbox, timeout, null);
240         }
241
242         /**
243          * Retrieves next task sent by a given host on the mailbox identified by the specified alias 
244          *
245      * @param mailbox
246      * @param host
247          */
248
249         public static Task receive(String mailbox, Host host) throws TransferFailureException, HostFailureException, TimeoutException {
250                 return receive(mailbox, -1.0, host);
251         }
252
253         /**
254          * Retrieves next task sent by a given host on the mailbox identified by the specified alias (wait at most \a timeout seconds)
255          *
256      * @param mailbox
257      * @param timeout 
258      * @param host
259          */
260         public native static Task receive(String mailbox, double timeout, Host host) throws TransferFailureException, HostFailureException, TimeoutException;
261         /**
262          * Tests whether there is a pending communication on the mailbox identified by the specified alias, and who sent it
263      */
264         public native static int listenFrom(String mailbox);
265         /**
266          * Listen whether there is a waiting task on the mailbox identified by the specified alias
267      */
268         public native static boolean listen(String mailbox);
269
270         /**
271          * 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.
272      */
273         public native static int listenFromHost(String alias, Host host);
274         
275         /**
276          * Class initializer, to initialize various JNI stuff
277          */
278         public static native void nativeInit();
279         static {
280                 nativeInit();
281         }
282 }