4 * Copyright 2006,2007 Martin Quinson, Malek Cherier
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.
13 #ifndef MSG_PROCESS_HPP
14 #define MSG_PROCESS_HPP
16 // Compilation C++ recquise
18 #error Process.hpp requires C++ compilation (use a .cxx suffix)
21 #include <msg/datatypes.h>
23 #include <MsgApplicationHandler.hpp>
26 #include <MsgException.hpp>
27 #include <NullPointerException.hpp>
28 #include <HostNotFoundException.hpp>
29 #include <ProcessNotFoundException.hpp>
30 #include <InvalidArgumentException.hpp>
31 #include <BadAllocException.hpp>
32 #include <LogicException.hpp>
38 class ApplicationHandler;
42 // SimGrid::Msg::Process class declaration.
43 class SIMGRIDX_EXPORT Process : public Object
45 friend class ApplicationHandler::ProcessFactory;
47 MSG_DECLARE_DYNAMIC(Process);
51 // Disable the default constructor.
55 /*! \brief Constructs a process from the name of the host and its name.
57 * \param hostName The host name of the process to create.
58 * \param name The name of the process to create.
60 * \exception If the constructor failed, it throws one of the exceptions described
63 * [NullPointerException] if the name of the process is NULL or if the
64 * name of the host is NULL.
65 * [HostNotFoundException] if the host is not found.
67 Process(const char* hostName, const char* name)
68 throw(NullPointerException, HostNotFoundException, BadAllocException);
70 /*! \brief Constructs a process from a reference to an host object and its name.
72 * \param rHost A reference to the host object representing the native
73 * MSG host where to create the process.
74 * \param name The name of the process to create.
76 * \exception If the constructor failed, it throws the exception described
79 * [NullPointerException] if the name of process is NULL.
81 Process(const Host& rHost, const char* name)
82 throw(NullPointerException);
84 /*! brief Construct a proces from reference to an host object and the name of the process.
85 * This constuctor takes also the list of the arguments of the process.
87 * \param host A reference to the host where to create the process.
88 * \param name The name of the process to create.
89 * \param argc The number of the arguments of the process to create.
90 * \param argv The list of arguments of the process to create.
92 * \exception If the constructor failed, it throws one of the exceptions described
95 * [NullPointerException] if the name of the host is NULL or
96 * if the name of the process is NULL.
97 * [InvalidArgumentException] if the value of the parameter argv is
99 * [LogicException] if the parameter argv is NULL and the
100 * parameter argc is different than zero
101 * if the parameter argv is not NULL and
102 * the parameter argc is zero.
104 Process(const Host& rHost, const char* name, int argc, char** argv)
105 throw(NullPointerException, InvalidArgumentException, LogicException);
107 /*! brief Constructs a proces from the name of a host and the name of the process.
108 * This constuctor takes also the list of the arguments of the process.
110 * \param hostName The name of the host where to create the process.
111 * \param name The name of the process to create.
112 * \param argc The number of the arguments of the process to create.
113 * \param argv The list of arguments of the process to create.
115 * \exception If the constructor failed, it throws one of the exceptions described
118 * [NullPointerException] if the name of the process or if the name
119 * of the host is NULL.
120 * [InvalidArgumentException] if the value of the parameter argv is
122 * [LogicException] if the parameter argv is NULL and the
123 * parameter argc is different than zero
124 * if the parameter argv is not NULL and
125 * the parameter argc is zero.
126 * [HostNotFoundException] if the specified host is no found.
128 Process(const char* hostName, const char* name, int argc, char** argv)
129 throw(NullPointerException, InvalidArgumentException, LogicException, HostNotFoundException, BadAllocException);
131 /*! \brief Process::killAll() - kill all the running processes of the simulation.
133 * \param resetPID Should we reset the PID numbers. A negative number means no reset
134 * and a positive number will be used to set the PID of the next newly
137 * \return The static method returns the PID of the next created process.
139 static int killAll(int resetPID);
141 /*! \brief Process::suspend() - Suspend an MSG process.
143 * \excetpion If this method failed, it throws one the exception described below:
145 * [MsgException] if an internal exception occurs during the operation.
152 /*! \brief Process::resume() - Resume the MSG process.
154 * \exception If this method failed, it throws the exception described below:
156 * [MsgException] if an internal exception occurs during the operation.
161 /*! \brief Process::isSuspend() - Tests if a process is suspended.
163 * \return This method returns 1 is the process is suspended.
164 * Otherwise the method returns 0.
166 int isSuspended(void);
168 /*! \brief Process::getHost() - Retrieves the host of a process object.
170 * \return The method returns a reference to the
171 * host of the process.
176 /*! \brief Process::fromPID() - Retrieves a process from its PID.
178 * \param PID The PID of the process to retrieve.
180 * \return If successful the method returns a reference to
181 * to process. Otherwise, the method throws one of
182 * the exceptions described below:
184 * \exception [ProcessNotFoundException] if the process is not found (no process with this PID).
186 * [InvalidArgumentException] if the parameter PID is less than 1.
188 * [MsgException] if a native error occurs during the operation.
190 static Process& fromPID(int PID)
191 throw(ProcessNotFoundException, InvalidArgumentException, MsgException);
193 /*! \brief Process::getPID() - Gets the PID of a process object.
195 * \return This method returns the PID of a process object.
199 /*! \brief Process::getPPID() - Gets the parent PID of a process object.
201 * \return This method returns the parent PID of a process object.
205 /*! \brief Process::getName() - Gets the name of a process object.
207 * \return This method returns the name of a process object.
209 const char* getName(void) const;
211 /*! \brief Process::currentProcess() - Retrieves the current process.
213 * \return This method returns a reference to the current process. Otherwise
214 * the method throws the excepction described below:
216 * \exception [MsgException] if an internal exception occurs.
218 static Process& currentProcess(void)
219 throw (MsgException);
221 /*! \brief Process::currentProcessPID() - Retrieves the PID of the current process.
223 * \return This method returns the PID of the current process.
225 static int currentProcessPID(void);
227 /*! \brief Process::currentProcessPPID() - Retrieves the parent PID of the current process.
229 * \return This method returns the parent PID of the current process.
231 static int currentProcessPPID(void);
233 /*! \brief Process::migrate() - Migrate a process object to an another host.
235 * \param rHost A reference to the host to migrate the process to.
237 * \return If successful the method migrate the process to the specified
238 * host. Otherwise the method throws the exception described
241 * \exception [MsgException] if an internal exception occurs.
243 void migrate(const Host& rHost)
246 /*! \brief Process::sleep() - Makes the current process sleep until time seconds have elapsed.
248 * \param seconds The number of seconds to sleep.
250 * \execption If this method failed, it throws one of the exceptions described
253 * [InvalidArgumentException] if the parameter seconds is
254 * less or equals to zero.
256 * [MsgException] if an internal exception occurs.
258 static void sleep(double seconds)
259 throw(InvalidArgumentException, MsgException);
261 /*! \brief Process::putTask() - This method puts a task on a given channel of a given host.
263 * \exception If this method failed, it throws one of the exceptions described
266 * [InvalidArgumentException] if the channel number is negative.
268 * [MsgException] if an internal exception occurs.
270 void putTask(const Host& rHost, int channel, Task* task)
271 throw(InvalidArgumentException, MsgException);
273 /*! \brief Process::putTask() - This method puts a task on a given channel of a given host (waiting at most given time).
275 * \exception If this method failed, it throws one of the exceptions described below:
277 * [MsgException] if an internal error occurs.
279 * [InvalidArgumentException] if the value of the channel specified as
280 * parameter is negative or if the timeout value
281 * is less than zero and différent of -1.
283 * \remark Set the timeout with -1.0 to disable it.
285 void putTask(const Host& rHost, int channel, Task* task, double timeout)
286 throw(InvalidArgumentException, MsgException);
288 /*! \brief Process::getTask() - Retrieves a task from a channel number (waiting at most given time).
290 * \param channel The number of the channel where to get the task.
292 * \return If successful the method returns a reference to
293 * the getted task. Otherwise the method throws one
294 * of the exceptions described below:
296 * \exception [InvalidArgumentException] if the channel number is negative.
298 * [MsgException] if an internal exception occurs.
300 Task* getTask(int channel)
301 throw(InvalidArgumentException, MsgException);
303 /*! \brief Process::taskGet() - Retrieves a task from a channel number (waiting at most given time).
305 * \param channel The number of the channel where to get the task.
306 * \param timeout The timeout value.
308 * \return If successful the method returns a reference to
309 * the getted task. Otherwise the method throws one
310 * of the exceptions described below:
312 * \exception [InvalidArgumentException] if the channel number is negative
313 * or if the timeout value is less than
314 * zero and different of -1.0.
315 * [MsgException] if an internal exception occurs.
317 Task* getTask(int channel, double timeout)
318 throw(InvalidArgumentException, MsgException);
320 /*! \brief Process::taskGet() - Retrieves a task from a channel number and a host.
322 * \param channel The number of the channel where to get the task.
323 * \param host The host of the channel to get the task.
325 * \return If successful the method returns a reference to
326 * the getted task. Otherwise the method throws one
327 * of the exceptions described below.
329 * \exception [InvalidArgumentException] if the channel number is negative.
330 * [MsgException] if an internal exception occurs.
332 Task* getTask(int channel, const Host& rHost)
333 throw(InvalidArgumentException, MsgException);
335 /*! \brief Process::taskGet() - Retrieves a task from a channel number and a host (waiting at most given time).
337 * \param channel The number of the channel where to get the task.
338 * \param timeout The timeout value.
339 * \param rHost The host owning the channel.
341 * \return If successful the method returns a reference to
342 * the getted task. Otherwise the method throws one
343 * of the exceptions described below:
345 * \exception [InvalidArgumentException] if the channel number is negative or
346 * if the timeout value is negative and different
348 * [MsgException] if an internal exception occurs.
350 * \remark Set the timeout with -1.0 to disable it.
352 Task* getTask(int channel, double timeout, const Host& rHost)
353 throw(InvalidArgumentException, MsgException);
355 /*! \brief Process::sendTask() - Sends the given task in the mailbox identified by the specified alias
356 * (waiting at most given time).
358 * \param alias The alias of the mailbox where to send the task.
359 * \param rTask A reference to the task object to send.
360 * \param timeout The timeout value.
362 * \exception If this method failed, it throws one of the exceptions described below:
364 * [NullPointerException] if the alias specified as parameter is NULL.
366 * [InvalidArgumentException] if the timeout value is negative and different than
368 * [MsgException] if an internal exception occurs.
370 * \remark Set the timeout with -1.0 to disable it.
372 void sendTask(const char* alias, Task* task, double timeout)
373 throw(NullPointerException, InvalidArgumentException, MsgException);
375 /*! \brief Process::sendTask() - Sends the given task in the mailbox identified by the specified alias.
377 * \param alias The alias of the mailbox where to send the task.
378 * \param rTask A reference to the task object to send.
380 * \exception If this method failed, it throws one of the exceptions described below:
382 * [NullPointerException] if the alias parameter is NULL.
384 * [MsgException] if an internal exception occurs.
387 void sendTask(const char* alias, Task* task)
388 throw(NullPointerException, MsgException);
390 /*! \brief Process::sendTask() - Sends the given task in the mailbox identified by the default alias.
392 * \param rTask A reference to the task object to send.
394 * \exception If this method failed, it throws one of the exceptions described below:
396 * [BadAllocException] if there is not enough memory to build the default alias.
398 * [MsgException] if an internal exception occurs.
401 void sendTask(Task* task)
402 throw(BadAllocException, MsgException);
404 /*! \brief Process::sendTask() - Sends the given task in the mailbox identified by the default alias
405 * (waiting at most given time).
407 * \param rTask A reference to the task object to send.
408 * \param timeout The timeout value.
410 * \exception If this method failed, it throws one of the exceptions described below:
412 * [BadAllocException] if there is not enough memory to build the default alias.
414 * [InvalidArgumentException] if the timeout value is negative and different than -1.0.
416 * [MsgException] if an internal exception occurs.
418 * \remark set the timeout value with -1.0 to disable it.
420 void sendTask(Task* task, double timeout)
421 throw(BadAllocException, InvalidArgumentException, MsgException);
423 /*! \brief Process::receiveTask() - Retrieves a task from the mailbox identified by the alias specified as
426 * \param alias The alias of the mailbox where to retrieve the task.
428 * \return If succcessful, the method returns a task of the mailbox. Otherwise, the method
429 * throws one of the exceptions described below:
431 * \exception [NullPointerException] if the parameter alias is NULL.
433 * [MsgException] if an internal exception occurs.
435 Task* receiveTask(const char* alias)
436 throw(NullPointerException, MsgException);
438 /*! \brief Process::receiveTask() - Retrieves a task from the mailbox identified by the default alias.
440 * \return If succcessful, the method returns a task of the mailbox. Otherwise, the method
441 * throws one of the exceptions described below:
443 * \exception [BadAllocException] if there is not enough memory to build the alias.
444 * [MsgException] if an internal exception occurs.
446 Task* receiveTask(void)
447 throw(BadAllocException, MsgException);
449 /*! \brief Process::receiveTask() - Retrieves a task from the mailbox identified by the alias specified as
450 * parameter(waiting at most given time).
452 * \param alias The alias of the mailbox where to retrieve the task.
453 * \param timeout The timeout value.
455 * \return If succcessful, the method returns a task of the mailbox. Otherwise, the method
456 * throws one of the exceptions described below.
458 * \exception [InvalidArgumentException] if the timeout value is negative or different of -1.0.
460 * [NullPointerException] if the parameter alias is NULL.
462 * [MsgException] if an internal exception occurs.
464 Task* receiveTask(const char* alias, double timeout)
465 throw(NullPointerException, InvalidArgumentException, MsgException);
467 /*! \brief Process::receiveTask() - Retrieves a task from the mailbox identified by the default alias
468 * (waiting at most given time).
470 * \param timeout The timeout value.
472 * \return If succcessful, the method returns a task of the mailbox. Otherwise, the method
473 * throws one of the exceptions described below:
475 * \exception [InvalidArgumentException] if the timeout value is negative or different than -1.0.
477 * [BadAllocException] if there is not enough memory to build the alias.
479 * [MsgException] if an internal exception occurs.
481 Task* receiveTask(double timeout)
482 throw(InvalidArgumentException, BadAllocException, MsgException);
484 /*! \brief Process::receiveTask() - Retrieves a task from the mailbox identified by the alias specified as
485 * parameter located on a given host (waiting at most given time).
487 * \param alias The alias of the mailbox where to retrieve the task.
488 * \param timeout The timeout value.
489 * \param rHost A reference to the host object owning the mailbox.
491 * \return If succcessful, the method returns a task of the mailbox. Otherwise, the method
492 * throws one of the exceptions described below:
494 * \exception [InvalidArgumentException] if the timeout value is negative or different of -1.0.
496 * [NullPointerException] if the parameter alias is NULL.
498 * [MsgException] if an internal exception occurs.
500 Task* receiveTask(const char* alias, double timeout, const Host& rHost)
501 throw(NullPointerException, InvalidArgumentException, MsgException);
503 /*! \brief Process::receiveTask() - Retrieves a task from the mailbox identified by default alias
504 * and located on a given host (waiting at most given time).
506 * \param timeout The timeout value.
507 * \param rHost A reference to the host object owning the mailbox.
509 * \return If succcessful, the method returns a task of the mailbox. Otherwise, the method
510 * throws one of the exceptions described below:
512 * \exception [InvalidArgumentException] if the timeout value is negative and different than -1.0.
514 * [BadAllocException] if there is not enough memory to build the default alias.
516 * [MsgException] if an internal exception occurs.
518 Task* receiveTask(double timeout, const Host& rHost)
519 throw(BadAllocException, InvalidArgumentException, MsgException);
521 /*! \brief Process::receiveTask() - Retrieves a task from the mailbox identified by the alias
522 * specified as parameter and located on a given host.
524 * \param alias The alias using to identify the mailbox from which to get the task.
525 * \param rHost A reference to the host object owning the mailbox.
527 * \return If succcessful, the method returns a task of the mailbox. Otherwise, the method
528 * throws one of the exceptions described below:
530 * \exception [NullPointerException] if the parameter alias is NULL.
532 * [MsgException] if an internal exception occurs.
534 Task* receiveTask(const char* alias, const Host& rHost)
535 throw(NullPointerException, MsgException);
537 /*! \brief Process::receiveTask() - Retrieves a task from the mailbox identified by default alias
538 * and located on a given host.
540 * \param rHost A reference to the host object owning the mailbox.
542 * \return If succcessful, the method returns a task of the mailbox. Otherwise, the method
543 * throws one of the exceptions described below:
545 * \exception [BadAllocException] if there is not enough memory to build the alias.
547 * [MsgException] if an internal exception occurs.
549 Task* receiveTask(const Host& rHost)
550 throw(BadAllocException, MsgException);
555 /* Process::create() - Creates a process on a given host.
557 * param rHost A reference to a host object where to create the process.
558 * param name The name of the process to create.
559 * param argc The number of argument to pass to the main function of the process.
560 * param argv The list of the arguments of the main function of the process.
562 * exception If this method failed, it throws one of the exceptions described below:
564 * [HostNotFoundException] if the host specified as parameter doesn't exist.
566 void create(const Host& rHost, const char* name, int argc, char** argv)
567 throw(InvalidArgumentException);
569 /* Process::fromNativeProcess() - Retrieves the process wrapper associated with a native process.
571 * \param nativeProcess The native process to get the wrapper.
573 * \return The wrapper associated with the native process specified as parameter.
575 static Process* fromNativeProcess(m_process_t nativeProcess);
580 /* Process::run() - used to set the field code of the context of the process.
582 static int run(int argc, char** argv);
584 /*! \brief Process::main() - This virtual pure function is the main function of the process.
585 * You must override this function for each new class of process that you create.
587 * \param argc The number of parameters of the main function.
588 * \param argv The list of the parameter of the main function.
590 * \return The exit code of the main function.
592 virtual int main(int argc, char** argv);
597 // Override the operator new().
598 void* operator new(size_t size);
600 // Override the operator delete().
601 void operator delete(void* p);
608 m_process_t nativeProcess; // pointer to the native msg process.
614 } // namespace SimGrid
616 #endif // !MSG_PROCESS_HPP