4 * This file contains the declaration of the wrapper class of the native MSG task type.
\r
6 * Copyright 2006,2007 Martin Quinson, Malek Cherier
\r
7 * All right reserved.
\r
9 * This program is free software; you can redistribute
\r
10 * it and/or modify it under the terms of the license
\r
11 *(GNU LGPL) which comes with this package.
\r
15 #ifndef MSG_TASK_HPP
\r
16 #define MSG_TASK_HPP
\r
18 // Compilation C++ recquise
\r
20 #error Process.hpp requires C++ compilation (use a .cxx suffix)
\r
27 // SimGrid::Msg::Task wrapper class declaration.
\r
31 // Default constructor.
\r
35 /*! \brief Copy constructor.
\r
37 Task(const Task& rTask);
\r
39 /*! \brief Destructor.
\r
41 * \exception If the destructor failed, it throw the exception described below:
\r
43 * [MsgException] if a native exception occurs.
\r
46 throw(MsgException);
\r
48 /*! \brief Constructs an new task with the specified processing amount and amount
\r
51 * \param name Task's name
\r
52 * \param computeDuration A value of the processing amount (in flop) needed to process the task.
\r
53 * If 0, then it cannot be executed with the execute() method.
\r
54 * This value has to be >= 0.
\r
55 * \param messageSize A value of amount of data (in bytes) needed to transfert this task.
\r
56 * If 0, then it cannot be transfered with the get() and put() methods.
\r
57 * This value has to be >= 0.
\r
59 * \exception If this method failed, it throws one of the exceptions described below:
\r
61 * [InvalidArgumentException] if the parameter computeDuration or messageSize
\r
63 * [NullPointerException] if the parameter name is NULL.
\r
65 * [MsgException] if a internal exception occurs.
\r
67 Task(const char* name, double computeDuration, double messageSize)
\r
68 throw (InvalidArgumentException, NullPointerException);
\r
70 /*! \Constructs an new parallel task with the specified processing amount and amount for each host
\r
73 * \param name The name of the parallel task.
\r
74 * \param hosts The list of hosts implied by the parallel task.
\r
75 * \param computeDurations The amount of operations to be performed by each host of \a hosts.
\r
76 * \param messageSizes A matrix describing the amount of data to exchange between hosts.
\r
77 * \hostCount The number of hosts implied in the parallel task.
\r
79 * \exception If this method fails, it throws one of the exceptions described below:
\r
81 * [NullPointerException] if the parameter name is NULL or
\r
82 * if the parameter computeDurations is NULL or
\r
83 * if the parameter messageSizes is NULL
\r
85 * [InvalidArgumentException] if the parameter hostCount is negative or zero.
\r
87 Task(const char* name, Host* hosts, double* computeDurations, double* messageSizes, int hostCount)
\r
88 throw(NullPointerException, InvalidArgumentException);
\r
91 /*! \brief Task::getName() - Gets the names of the task.
\r
93 * \return The name of the task.
\r
95 const char* getName(void) const;
\r
97 /*! \brief Task::getSender() - Gets the sender of the task.
\r
99 * \return A reference to the sender of the task.
\r
101 Process& getSender(void) const;
\r
103 /*! \brief Task::getSource() - Gets the source of the task.
\r
105 * \return A reference to the source of the task.
\r
107 Host& getSource(void) const;
\r
109 /*! \brief Task::getComputeDuration() - Get the computing amount of the task.
\r
111 * \return The computing amount of the task.
\r
114 double getComputeDuration(void) const;
\r
116 /*! \brief Task::getRemainingDuration() - Gets the remaining computation.
\r
118 * \return The remining computation of the task.
\r
120 double getRemainingDuration(void) const;
\r
122 /*! \brief Task::setPrirority() - Sets the priority of the computation of the task.
\r
123 * The priority doesn't affect the transfert rate. For example a
\r
124 * priority of 2 will make the task receive two times more cpu than
\r
127 * \param priority The new priority of the task.
\r
129 * execption If this method fails, it throws the exception described below:
\r
131 * [InvalidArgumentException] if the parameter priority is negative.
\r
133 void setPriority(double priority)
\r
134 throw(InvalidArgumentException);
\r
136 /*! \brief Task::get() - Gets a task from the specified channel of the host of the current process.
\r
138 * \param channel The channel number to get the task.
\r
140 * \return If successful the method returns the task. Otherwise the method throws one
\r
141 * of the exceptions described below:
\r
143 * \exception [InvalidArgumentException] if the channel parameter is negative.
\r
145 * [MsgException] if an internal excpetion occurs.
\r
147 static Task& get(int channel)
\r
148 throw(InvalidArgumentException, MsgException);
\r
150 /*! \brief Task::get() - Gets a task from the given channel number of the given host.
\r
152 * \param channel The channel number.
\r
153 * \param rHost A reference of the host owning the channel.
\r
155 * \return If successful, the method returns the task. Otherwise the method
\r
156 * throw one of the exceptions described below:
\r
158 * \exception [InvalidArgumentException] if the channel number is negative.
\r
160 * [MsgException] if an internal exception occurs.
\r
162 static Task& get(int channel, const Host& rHost)
\r
163 throw(InvalidArgumentException, MsgException);
\r
165 /*! \brief Task::get() - Gets a task from the specified channel of the specified host
\r
166 * (waiting at most given time).
\r
168 * \param channel The channel number.
\r
169 * \param timeout The timeout value.
\r
170 * \param rHost A reference to the host owning the channel.
\r
172 * \return If successful, the method returns the task. Otherwise the method returns
\r
173 * one of the exceptions described below:
\r
175 * \exception [InvalidArgumentException] if the channel number is negative or
\r
176 * if the timeout value is negative and
\r
177 * different than -1.0.
\r
178 * [MsgException] if an internal exception occurs.
\r
180 static Task& get(int channel, double timeout, const Host& rHost)
\r
181 throw(InvalidArgumentException, MsgException);
\r
183 /*! \brief Task::probe() - Probes whether there is a waiting task on the given channel of local host.
\r
185 * \param channel The channel number.
\r
187 * \return If there is a waiting task on the channel the method returns true. Otherwise
\r
188 * the method returns false.
\r
190 * \exception If this method fails, it throws the exception described below:
\r
192 * [InvalidArgumentException] if the parameter channel is negative.
\r
194 static bool probe(int channel)
\r
195 throw(InvalidArgumentException);
\r
197 /*! \brief Task::probe() - Counts tasks waiting on the given channel of local host and sent by given host.
\r
199 * \param channel The channel id.
\r
200 * \param rHost A reference to the host that has sent the task.
\r
202 * \return The number of tasks.
\r
204 * \exception [InvalidArgumentException] if the parameter channel is negative.
\r
206 static int probe(int channel, const Host& rHost)
\r
207 throw(InvalidArgumentException);
\r
209 /*! \brief Task::execute() - This method executes a task on the location on which the
\r
210 * process is running.
\r
212 * \exception If this method fails, it returns the exception described below:
\r
214 * [MsgException] if an internal exception occurs.
\r
216 void execute(void)
\r
217 throw(MsgException);
\r
219 /*! \brief Task::cancel() - This method cancels a task.
\r
221 * \exception If this method fails, it returns the exception described below:
\r
223 * [MsgException] if an internal exception occurs.
\r
226 throw(MsgException);
\r
228 /*! \brief Task::send() - Send the task on the mailbox identified by the default alias.
\r
230 * \exception If this method failed, it returns one of the exceptions described
\r
233 * [BadAllocException] if there is not enough memory to build the default alias.
\r
235 * [MsgException] if an internal exception occurs.
\r
238 throw(BadAllocException, MsgException);
\r
240 /*! \brief Task::send() - Send the task on the mailbox identified by the given alias.
\r
242 * \param alias The alias of the mailbox where to send the task.
\r
244 * \exception If this method failed, it returns one of the exceptions described
\r
247 * [NullPointerException] if there parameter alias is NULL.
\r
249 * [MsgException] if an internal exception occurs.
\r
251 void send(const char* alias)
\r
252 throw(NullPointerException, MsgException);
\r
254 /*! \brief Task::send() - Send the task on the mailbox identified by the default alias
\r
255 * (waiting at most given time).
\r
257 * \param timeout The timeout value.
\r
259 * \exception If this method failed, it returns one of the exceptions described
\r
262 * [BadAllocException] if there is not enough memory to build the default alias.
\r
264 * [InvalidArgumentException] if the timeout value is negative or different -1.0.
\r
266 * [MsgException] if an internal exception occurs.
\r
268 void send(double timeout)
\r
269 throw(BadAllocationException, InvalidArgumentException, MsgException);
\r
271 /*! \brief Task::send() - Send the task on the mailbox identified by a given alias
\r
272 * (waiting at most given time).
\r
274 * \param alias The alias of the mailbox where to send the task.
\r
275 * \param timeout The timeout value.
\r
277 * \exception If this method failed, it returns one of the exceptions described
\r
280 * [NullPointerException] if alias parameter is NULL.
\r
282 * [InvalidArgumentException] if the timeout value is negative or different -1.0.
\r
284 * [MsgException] if an internal exception occurs.
\r
286 void send(const char* alias, double timeout)
\r
287 throw(NullPointerException, InvalidArgumentException, MsgException);
\r
289 /*! \brief Task::sendBounded() - Sends the task on the mailbox identified by the default alias.
\r
290 * (capping the emision rate to maxrate).
\r
292 * \param maxRate The maximum rate value.
\r
294 * \exception If this method failed, it throws one of the exceptions described below:
\r
296 * [BadAllocException] if there is not enough memory to build the default alias.
\r
298 * [InvalidArgumentException] if the parameter maxRate is negative and different
\r
301 * [MsgException] if an internal exception occurs.
\r
303 void sendBounded(double maxRate)
\r
304 throw(BadAllocException, InvalidArgumentException, MsgException);
\r
306 /*! \brief Task::sendBounded() - Sends the task on the mailbox identified by the given alias.
\r
307 * (capping the emision rate to maxrate).
\r
309 *\ param alias The alias of the mailbox where to send the task.
\r
310 * \param maxRate The maximum rate value.
\r
312 * \exception If this method failed, it throws one of the exceptions described below:
\r
314 * [NullPointerException] if the alias parameter is NULL.
\r
316 * [InvalidArgumentException] if the parameter maxRate is negative and different
\r
319 * [MsgException] if an internal exception occurs.
\r
321 void sendBounded(const char* alias, double maxRate)
\r
322 throw(NullPointerException, InvalidArgumentException, MsgException);
\r
325 /*! \brief Task::receive() - Receives a task from the mailbox identified by the default alias (located
\r
326 * on the local host).
\r
328 * \return A reference to the task.
\r
330 * \exception If this method failed, it throws one of the exception described below:
\r
332 * [BadAllocException] if there is not enough memory to build the default alias.
\r
334 * [MsgException] if an internal exception occurs.
\r
336 static Task& receive(void)
\r
337 throw(BadAllocException, MsgException);
\r
339 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias (located
\r
340 * on the local host).
\r
342 * \alias The alias of the mailbox.
\r
344 * \return A reference to the task.
\r
346 * \exception If this method failed, it throws one of the exception described below:
\r
348 * [NullPointerException] if the alias parameter is NULL.
\r
350 * [MsgException] if an internal exception occurs.
\r
352 static Task& receive(const char* alias)
\r
353 throw(NullPointerException, MsgException);
\r
355 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias (located
\r
356 * on the local host and waiting at most given time).
\r
358 * \alias The alias of the mailbox.
\r
359 * \timeout The timeout value.
\r
361 * \return A reference to the task.
\r
363 * \exception If this method failed, it throws one of the exception described below:
\r
365 * [NullPointerException] if the alias parameter is NULL.
\r
367 * [InvalidArgumentException] if the timeout value is negatif and different than
\r
370 * [MsgException] if an internal exception occurs.
\r
372 static Task& receive(const char* alias, double timeout)
\r
373 throw(NullPointerException, InvalidArgumentException, MsgException);
\r
375 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias located
\r
376 * on the given host.
\r
378 * \alias The alias of the mailbox.
\r
379 * \rHost The location of the mailbox.
\r
381 * \return A reference to the task.
\r
383 * \exception If this method failed, it throws one of the exception described below:
\r
385 * [NullPointerException] if the alias parameter is NULL.
\r
387 * [MsgException] if an internal exception occurs.
\r
389 static Task& receive(const char* alias, const Host& rHost)
\r
390 throw(NullPointerException, MsgException);
\r
392 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias located
\r
393 * on the given host (and waiting at most given time).
\r
395 * \alias The alias of the mailbox.
\r
396 * \timeout The timeout value.
\r
397 * \rHost The location of the mailbox.
\r
399 * \return A reference to the task.
\r
401 * \exception If this method failed, it throws one of the exception described below:
\r
403 * [NullPointerException] if the alias parameter is NULL.
\r
405 * [InvalidArgumentException] if the timeout value is negatif and different than
\r
408 * [MsgException] if an internal exception occurs.
\r
410 static Task& receive(const char* alias, double timeout, const Host& rHost)
\r
411 throw(NullPointerException, InvalidArgumentException, MsgException);
\r
413 /*! \brief Task::listen() - Listen whether there is a waiting task on the mailbox
\r
414 * identified by the default alias of local host.
\r
416 * \return If there is a waiting task on the mailbox the method returns true.
\r
417 * Otherwise the method returns false.
\r
419 * \exception If this method fails, it throws one of the exceptions described below:
\r
421 * [BadAllocException] if there is not enough memory to build the default alias.
\r
423 static bool listen(void)
\r
424 throw(BadAllocException);
\r
426 /*! \brief Task::listen() - Listen whether there is a waiting task on the mailbox
\r
427 * identified by the given alias of local host.
\r
429 * \param alias The alias of the mailbox.
\r
431 * \return If there is a waiting task on the mailbox the method returns true.
\r
432 * Otherwise the method returns false.
\r
434 * \exception If this method fails, it throws one of the exceptions described below:
\r
436 * [NullPointerException] if the parameter alias is NULL.
\r
438 static bool listen(const char* alias)
\r
439 throw(NullPointerException);
\r
441 /*! \brief Task::listenFrom() - Tests whether there is a pending communication on the mailbox
\r
442 * identified by the default alias, and who sent it.
\r
444 * \return If there is a pending communication on the mailbox, the method returns
\r
445 * the PID of it sender. Otherwise the method returns -1.
\r
447 * \exception If this method fails, it throws the exception described below:
\r
449 * [BadAllocException] if there is not enough memory to build the default
\r
452 static int listenFrom(void)
\r
453 throw(BadAllocException);
\r
455 /*! \brief Task::listenFrom() - Tests whether there is a pending communication on the mailbox
\r
456 * identified by the specified alias, and who sent it.
\r
458 * \alias The alias of the mailbox.
\r
460 * \return If there is a pending communication on the mailbox, the method returns
\r
461 * the PID of it sender. Otherwise the method returns -1.
\r
463 * \exception If this method fails, it throws the exception described below:
\r
465 * [NullPointerException] if the alias parameter is NULL.
\r
467 static int listenFrom(const char* alias)
\r
468 throw(NullPointerException);
\r
470 /*! \brief Task::listenFromHost() - Tests whether there is a pending communication on the mailbox
\r
471 * identified by the default alias and located on the host of the current process, and who sent it.
\r
473 * \param rHost The location of the mailbox.
\r
475 * \return If there is a pending communication on the mailbox, the method returns
\r
476 * the PID of it sender. Otherwise the method returns -1.
\r
478 * \exception If this method fails, it throws the exception described below:
\r
480 * [BadAllocException] if there is not enough memory to build the default
\r
483 static int listenFromHost(const Host& rHost)
\r
484 throw(BadAllocException);
\r
486 /*! \brief Task::listenFromHost() - Tests whether there is a pending communication on the mailbox
\r
487 * identified by the default alias and located on the host of the current process, and who sent it.
\r
489 * \param rHost The location of the mailbox.
\r
491 * \return If there is a pending communication on the mailbox, the method returns
\r
492 * the PID of it sender. Otherwise the method returns -1.
\r
494 * \exception If this method fails, it throws the exception described below:
\r
496 * [BadAllocException] if there is not enough memory to build the default
\r
499 static bool listenFromHost(const char* alias, const Host& rHost)
\r
500 throw(NullPointerException, NativeException);
\r
506 m_task_t nativeTask; // the native MSG task.
\r
509 } // namespace Msg
\r
510 } // namespace SimGrid
\r
512 #endif // §MSG_TASK_HPP