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