4 * This file contains the declaration of the wrapper class of the native MSG task type.
6 * Copyright 2006,2007 Martin Quinson, Malek Cherier
9 * This program is free software; you can redistribute
10 * it and/or modify it under the terms of the license
11 *(GNU LGPL) which comes with this package.
18 // Compilation C++ recquise
20 #error Task.hpp requires C++ compilation (use a .cxx suffix)
23 #include <msg/datatypes.h>
25 #include <MsgException.hpp>
26 #include <InvalidArgumentException.hpp>
27 #include <NullPointerException.hpp>
28 #include <MsgException.hpp>
29 #include <BadAllocException.hpp>
40 // SimGrid::Msg::Task wrapper class declaration.
41 class SIMGRIDX_EXPORT Task : public Object
43 MSG_DECLARE_DYNAMIC(Task);
49 // Default constructor.
53 /*! \brief Copy constructor.
55 Task(const Task& rTask);
57 /*! \brief Destructor.
59 * \exception If the destructor failed, it throw the exception described below:
61 * [MsgException] if a native exception occurs.
66 /*! \brief Constructs an new task with the specified processing amount and amount
69 * \param name Task's name
70 * \param computeDuration A value of the processing amount (in flop) needed to process the task.
71 * If 0, then it cannot be executed with the execute() method.
72 * This value has to be >= 0.
73 * \param messageSize A value of amount of data (in bytes) needed to transfert this task.
74 * If 0, then it cannot be transfered with the get() and put() methods.
75 * This value has to be >= 0.
77 * \exception If this method failed, it throws one of the exceptions described below:
79 * [InvalidArgumentException] if the parameter computeDuration or messageSize
81 * [NullPointerException] if the parameter name is NULL.
83 * [MsgException] if a internal exception occurs.
85 Task(const char* name, double computeDuration, double messageSize)
86 throw (InvalidArgumentException, NullPointerException);
88 /*! \Constructs an new parallel task with the specified processing amount and amount for each host
91 * \param name The name of the parallel task.
92 * \param hosts The list of hosts implied by the parallel task.
93 * \param computeDurations The amount of operations to be performed by each host of \a hosts.
94 * \param messageSizes A matrix describing the amount of data to exchange between hosts.
95 * \hostCount The number of hosts implied in the parallel task.
97 * \exception If this method fails, it throws one of the exceptions described below:
99 * [NullPointerException] if the parameter name is NULL or
100 * if the parameter computeDurations is NULL or
101 * if the parameter messageSizes is NULL
103 * [InvalidArgumentException] if the parameter hostCount is negative or zero.
105 Task(const char* name, Host* hosts, double* computeDurations, double* messageSizes, int hostCount)
106 throw(NullPointerException, InvalidArgumentException);
109 /*! \brief Task::getName() - Gets the names of the task.
111 * \return The name of the task.
113 const char* getName(void) const;
115 /*! \brief Task::getSender() - Gets the sender of the task.
117 * \return A reference to the sender of the task.
119 Process& getSender(void) const;
121 /*! \brief Task::getSource() - Gets the source of the task.
123 * \return A reference to the source of the task.
125 Host& getSource(void) const;
127 /*! \brief Task::getComputeDuration() - Get the computing amount of the task.
129 * \return The computing amount of the task.
132 double getComputeDuration(void) const;
134 /*! \brief Task::getRemainingDuration() - Gets the remaining computation.
136 * \return The remining computation of the task.
138 double getRemainingDuration(void) const;
140 /*! \brief Task::setPrirority() - Sets the priority of the computation of the task.
141 * The priority doesn't affect the transfert rate. For example a
142 * priority of 2 will make the task receive two times more cpu than
145 * \param priority The new priority of the task.
147 * execption If this method fails, it throws the exception described below:
149 * [InvalidArgumentException] if the parameter priority is negative.
151 void setPriority(double priority)
152 throw(InvalidArgumentException);
154 /*! \brief Task::get() - Gets a task from the specified channel of the host of the current process.
156 * \param channel The channel number to get the task.
158 * \return If successful the method returns the task. Otherwise the method throws one
159 * of the exceptions described below:
161 * \exception [InvalidArgumentException] if the channel parameter is negative.
163 * [MsgException] if an internal excpetion occurs.
165 static Task* get(int channel)
166 throw(InvalidArgumentException, MsgException);
168 /*! \brief Task::get() - Gets a task from the given channel number of the given host.
170 * \param channel The channel number.
171 * \param rHost A reference of the host owning the channel.
173 * \return If successful, the method returns the task. Otherwise the method
174 * throw one of the exceptions described below:
176 * \exception [InvalidArgumentException] if the channel number is negative.
178 * [MsgException] if an internal exception occurs.
180 static Task* get(int channel, const Host& rHost)
181 throw(InvalidArgumentException, MsgException);
183 /*! \brief Task::get() - Gets a task from the specified channel of the specified host
184 * (waiting at most given time).
186 * \param channel The channel number.
187 * \param timeout The timeout value.
188 * \param rHost A reference to the host owning the channel.
190 * \return If successful, the method returns the task. Otherwise the method returns
191 * one of the exceptions described below:
193 * \exception [InvalidArgumentException] if the channel number is negative or
194 * if the timeout value is negative and
195 * different than -1.0.
196 * [MsgException] if an internal exception occurs.
198 static Task* get(int channel, double timeout, const Host& rHost)
199 throw(InvalidArgumentException, MsgException);
201 /*! \brief Task::probe() - Probes whether there is a waiting task on the given channel of local host.
203 * \param channel The channel number.
205 * \return If there is a waiting task on the channel the method returns 1. Otherwise
206 * the method returns 0.
208 * \exception If this method fails, it throws the exception described below:
210 * [InvalidArgumentException] if the parameter channel is negative.
212 static int probe(int channel)
213 throw(InvalidArgumentException);
215 /*! \brief Task::probe() - Counts tasks waiting on the given channel of local host and sent by given host.
217 * \param channel The channel id.
218 * \param rHost A reference to the host that has sent the task.
220 * \return The number of tasks.
222 * \exception [InvalidArgumentException] if the parameter channel is negative.
224 static int probe(int channel, const Host& rHost)
225 throw(InvalidArgumentException);
227 /*! \brief Task::execute() - This method executes a task on the location on which the
228 * process is running.
230 * \exception If this method fails, it returns the exception described below:
232 * [MsgException] if an internal exception occurs.
237 /*! \brief Task::cancel() - This method cancels a task.
239 * \exception If this method fails, it returns the exception described below:
241 * [MsgException] if an internal exception occurs.
246 /*! \brief Task::send() - Send the task on the mailbox identified by the default alias.
248 * \exception If this method failed, it returns one of the exceptions described
251 * [BadAllocException] if there is not enough memory to build the default alias.
253 * [MsgException] if an internal exception occurs.
256 throw(BadAllocException, MsgException);
258 /*! \brief Task::send() - Send the task on the mailbox identified by the given alias.
260 * \param alias The alias of the mailbox where to send the task.
262 * \exception If this method failed, it returns one of the exceptions described
265 * [NullPointerException] if there parameter alias is NULL.
267 * [MsgException] if an internal exception occurs.
269 void send(const char* alias)
270 throw(NullPointerException, MsgException);
272 /*! \brief Task::send() - Send the task on the mailbox identified by the default alias
273 * (waiting at most given time).
275 * \param timeout The timeout value.
277 * \exception If this method failed, it returns one of the exceptions described
280 * [BadAllocException] if there is not enough memory to build the default alias.
282 * [InvalidArgumentException] if the timeout value is negative or different -1.0.
284 * [MsgException] if an internal exception occurs.
286 void send(double timeout)
287 throw(BadAllocException, InvalidArgumentException, MsgException);
289 /*! \brief Task::send() - Send the task on the mailbox identified by a given alias
290 * (waiting at most given time).
292 * \param alias The alias of the mailbox where to send the task.
293 * \param timeout The timeout value.
295 * \exception If this method failed, it returns one of the exceptions described
298 * [NullPointerException] if alias parameter is NULL.
300 * [InvalidArgumentException] if the timeout value is negative or different -1.0.
302 * [MsgException] if an internal exception occurs.
304 void send(const char* alias, double timeout)
305 throw(NullPointerException, InvalidArgumentException, MsgException);
307 /*! \brief Task::sendBounded() - Sends the task on the mailbox identified by the default alias.
308 * (capping the emision rate to maxrate).
310 * \param maxRate The maximum rate value.
312 * \exception If this method failed, it throws one of the exceptions described below:
314 * [BadAllocException] if there is not enough memory to build the default alias.
316 * [InvalidArgumentException] if the parameter maxRate is negative and different
319 * [MsgException] if an internal exception occurs.
321 void sendBounded(double maxRate)
322 throw(BadAllocException, InvalidArgumentException, MsgException);
324 /*! \brief Task::sendBounded() - Sends the task on the mailbox identified by the given alias.
325 * (capping the emision rate to maxrate).
327 *\ param alias The alias of the mailbox where to send the task.
328 * \param maxRate The maximum rate value.
330 * \exception If this method failed, it throws one of the exceptions described below:
332 * [NullPointerException] if the alias parameter is NULL.
334 * [InvalidArgumentException] if the parameter maxRate is negative and different
337 * [MsgException] if an internal exception occurs.
339 void sendBounded(const char* alias, double maxRate)
340 throw(NullPointerException, InvalidArgumentException, MsgException);
343 /*! \brief Task::receive() - Receives a task from the mailbox identified by the default alias (located
344 * on the local host).
346 * \return A reference to the task.
348 * \exception If this method failed, it throws one of the exception described below:
350 * [BadAllocException] if there is not enough memory to build the default alias.
352 * [MsgException] if an internal exception occurs.
354 /*static Task& receive(void)
355 throw(BadAllocException, MsgException);*/
357 static Task* receive(void)
358 throw(BadAllocException, MsgException);
360 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias (located
361 * on the local host).
363 * \alias The alias of the mailbox.
365 * \return A reference to the task.
367 * \exception If this method failed, it throws one of the exception described below:
369 * [NullPointerException] if the alias parameter is NULL.
371 * [MsgException] if an internal exception occurs.
373 /*static Task& receive(const char* alias)
374 throw(NullPointerException, MsgException);*/
375 static Task* receive(const char* alias)
376 throw(NullPointerException, MsgException);
378 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias (located
379 * on the local host and waiting at most given time).
381 * \alias The alias of the mailbox.
382 * \timeout The timeout value.
384 * \return A reference to the task.
386 * \exception If this method failed, it throws one of the exception described below:
388 * [NullPointerException] if the alias parameter is NULL.
390 * [InvalidArgumentException] if the timeout value is negatif and different than
393 * [MsgException] if an internal exception occurs.
395 static Task* receive(const char* alias, double timeout)
396 throw(NullPointerException, InvalidArgumentException, MsgException);
398 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias located
401 * \alias The alias of the mailbox.
402 * \rHost The location of the mailbox.
404 * \return A reference to the task.
406 * \exception If this method failed, it throws one of the exception described below:
408 * [NullPointerException] if the alias parameter is NULL.
410 * [MsgException] if an internal exception occurs.
412 static Task* receive(const char* alias, const Host& rHost)
413 throw(NullPointerException, MsgException);
415 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias located
416 * on the given host (and waiting at most given time).
418 * \alias The alias of the mailbox.
419 * \timeout The timeout value.
420 * \rHost The location of the mailbox.
422 * \return A reference to the task.
424 * \exception If this method failed, it throws one of the exception described below:
426 * [NullPointerException] if the alias parameter is NULL.
428 * [InvalidArgumentException] if the timeout value is negatif and different than
431 * [MsgException] if an internal exception occurs.
433 static Task* receive(const char* alias, double timeout, const Host& rHost)
434 throw(NullPointerException, InvalidArgumentException, MsgException);
436 /*! \brief Task::listen() - Listen whether there is a waiting task on the mailbox
437 * identified by the default alias of local host.
439 * \return If there is a waiting task on the mailbox the method returns true.
440 * Otherwise the method returns false.
442 * \exception If this method fails, it throws one of the exceptions described below:
444 * [BadAllocException] if there is not enough memory to build the default alias.
446 static int listen(void)
447 throw(BadAllocException);
449 /*! \brief Task::listen() - Listen whether there is a waiting task on the mailbox
450 * identified by the given alias of local host.
452 * \param alias The alias of the mailbox.
454 * \return If there is a waiting task on the mailbox the method returns 1.
455 * Otherwise the method returns 0.
457 * \exception If this method fails, it throws one of the exceptions described below:
459 * [NullPointerException] if the parameter alias is NULL.
461 static int listen(const char* alias)
462 throw(NullPointerException);
464 /*! \brief Task::listenFrom() - Tests whether there is a pending communication on the mailbox
465 * identified by the default alias, and who sent it.
467 * \return If there is a pending communication on the mailbox, the method returns
468 * the PID of it sender. Otherwise the method returns -1.
470 * \exception If this method fails, it throws the exception described below:
472 * [BadAllocException] if there is not enough memory to build the default
475 static int listenFrom(void)
476 throw(BadAllocException);
478 /*! \brief Task::listenFrom() - Tests whether there is a pending communication on the mailbox
479 * identified by the specified alias, and who sent it.
481 * \alias The alias of the mailbox.
483 * \return If there is a pending communication on the mailbox, the method returns
484 * the PID of it sender. Otherwise the method returns -1.
486 * \exception If this method fails, it throws the exception described below:
488 * [NullPointerException] if the alias parameter is NULL.
490 static int listenFrom(const char* alias)
491 throw(NullPointerException);
493 /*! \brief Task::listenFromHost() - Tests whether there is a pending communication on the mailbox
494 * identified by the default alias and located on the host of the current process, and who sent it.
496 * \param rHost The location of the mailbox.
498 * \return If there is a pending communication on the mailbox, the method returns
499 * the PID of it sender. Otherwise the method returns -1.
501 * \exception If this method fails, it throws the exception described below:
503 * [BadAllocException] if there is not enough memory to build the default
506 static int listenFromHost(const Host& rHost)
507 throw(BadAllocException);
509 /*! \brief Task::listenFromHost() - Tests whether there is a pending communication on the mailbox
510 * identified by the default alias and located on the host of the current process, and who sent it.
512 * \param rHost The location of the mailbox.
514 * \return If there is a pending communication on the mailbox, the method returns
515 * the PID of it sender. Otherwise the method returns -1.
517 * \exception If this method fails, it throws the exception described below:
519 * [BadAllocException] if there is not enough memory to build the default
522 static int listenFromHost(const char* alias, const Host& rHost)
523 throw(NullPointerException);
525 virtual const Task& operator= (const Task& rTask);
531 m_task_t nativeTask; // the native MSG task.
535 } // namespace SimGrid
537 typedef Task* TaskPtr;
539 #endif // §MSG_TASK_HPP