4 * Copyright 2006,2007 Martin Quinson, Malek Cherier
\r
5 * All right reserved.
\r
7 * This program is free software; you can redistribute
\r
8 * it and/or modify it under the terms of the license
\r
9 *(GNU LGPL) which comes with this package.
\r
12 #ifndef MSG_HOST_HPP
\r
13 #define MSG_HOST_HPP
\r
16 /*! \brief Host class declaration.
\r
18 * An host instance represents a location (any possible place) where a process may run.
\r
19 * Thus it is represented as a physical resource with computing capabilities, some
\r
20 * mailboxes to enable running process to communicate with remote ones, and some private
\r
21 * data that can be only accessed by local process. An instance of this class is always
\r
22 * binded with the corresponding native host. All the native hosts are automaticaly created
\r
23 * during the call of the static method Msg::createEnvironment(). This method takes as parameter
\r
24 * the platform file which describes all elements of the platform (host, link, root..).
\r
25 * You never need to create an host your self.
\r
27 * The best way to get an host is to call the static method
\r
28 * Host.getByName() which returns a reference.
\r
30 * For example to get the instance of the host. If your platform
\r
31 * file description contains an host named "Jacquelin" :
\r
34 using namespace SimGrid.Msg;
\r
40 jacquelin = Host::getByName("Jacquelin");
\r
42 catch(HostNotFoundException e)
\r
44 cerr << e.toString();
\r
52 #error Host.hpp requires C++ compilation (use a .cxx suffix)
\r
55 #include <msg/datatypes.h>
\r
57 #include <InvalidArgumentException.hpp>
\r
58 #include <BadAllocException.hpp>
\r
59 #include <HostNotFoundException.hpp>
\r
60 #include <MsgException.hpp>
\r
61 #include <NullPointerException.hpp>
\r
65 // namespace SimGrid::Msg
\r
73 // Declaration of the class SimGrid::Msg::Host.
\r
74 class SIMGRIDX_EXPORT Host // final class.
\r
76 friend class Process;
\r
79 // Desable the default constructor.
\r
80 // The best way to get an host instance is to use the static method Host::getByName().
\r
84 // Default constructor (desabled).
\r
89 // Copy constructor (desabled).
\r
90 Host(const Host& rHost);
\r
92 // Destructor (desable).
\r
97 /*! \brief Host::getByName() - returns an host by its name
\r
99 * This static method returns a reference to the host instance associated
\r
100 * with a native host of your platform. This is the best way to get a host.
\r
102 * \param hostName The name of the host.
\r
104 * \return If successful the method returns a reference to the instance
\r
105 * associated with the native host having the name specified
\r
106 * as parameter of your platform. Otherwise the method throws
\r
107 * one of the exceptions detailed below.
\r
109 * \exception [HostNotFoundException] if no host with the specified name
\r
111 * [InvalidArgumentException] if the hostName parameter is invalid (NULL).
\r
112 * [BadAllocException] if there is not enough memory to allocate the host.
\r
114 static Host& getByName(const char* hostName)
\r
115 throw(HostNotFoundException, NullPointerException, BadAllocException);
\r
117 /*! \brief Host::getNumber() - returns the number of the installed hosts.
\r
119 * \return The number of hosts installed.
\r
121 static int getNumber(void);
\r
124 /*! \brief Host::currentHost() - This static method returns the location on which the current
\r
125 * process is executed.
\r
127 * \return The host of the current process.
\r
129 * \see Process::currentProcess().
\r
131 static Host& currentHost(void);
\r
133 /*! \brief Host::all() - This static method retrieves all of the hosts of the installed platform.
\r
135 * \param hosts A pointer to array of Host pointers that receives all the hosts of the platform.
\r
137 * \param len A pointer to the length of the table of pointers.
\r
139 * \return If successful the hosts table is filled and
\r
140 * the parameter len is set with the number of hosts of the platform.
\r
141 * Otherwise the method throw one of the exception described below.
\r
143 * \exception [InvalidArgumentException] if the parameter hosts is invalid or
\r
144 * if the parameter len is negative or
\r
145 * less than the number of hosts installed
\r
146 * on the current platform.
\r
147 * [BadAllocException] If the method can't allocate memory to fill
\r
148 * the table of hosts.
\r
151 * \remark To get the number of hosts installed on your platform use the static method
\r
152 * Host::getNumber().
\r
154 * \see Host::getNumber().
\r
157 * // This example show how to use this method to get the list of hosts installed on your platform.
\r
159 * using namespace SimGrid::Msg;
\r
162 * // (1) get the number of hosts.
\r
163 * int number = Host::getNumber();
\r
165 * // (2) allocate the array that receives the list of hosts.
\r
166 * HostPtr* ar = new HostPtr[number]; // HostPtr is defined as (typedef Host* HostPtr at the end of the
\r
167 * // declaration of this class.
\r
169 * // (3) call the method
\r
172 * Host::all(&ar, &number);
\r
174 * catch(BadAllocException e)
\r
176 * cerr << e.toString() << endl;
\r
179 * catch(InvalidArgumentException e)
\r
181 * cerr << e.toString() << endl;
\r
185 * // (4) use the table of host (for example print all the name of all the hosts);
\r
187 * for(int i = 0; i < number ; i++)
\r
188 * cout << ar[i]->getName() << endl;
\r
192 * // (5) release the allocate table
\r
197 static void all(Host*** hosts /*in|out*/, int* len /*in|out*/)
\r
198 throw(InvalidArgumentException, BadAllocException) ;
\r
200 /*! \brief Host::getName() - This method return the name of the Msg host object.
\r
202 * \return The name of the host object.
\r
204 const char* getName(void) const;
\r
206 /*! \brief Host::setData() - Set the user data of an host object.
\r
208 * \param data The user data to set.
\r
210 void setData(void* data);
\r
212 /*! \brief Host::getData() - Get the user data of a host object.
\r
214 * \return The user data of the host object.
\r
216 void* getData(void) const;
\r
218 /*! \brief Host::hasData() - Test if an host object has some data.
\r
220 * \return This method returns true if the host object has some user data.
\r
221 * Otherwise the method returns false.
\r
223 bool hasData(void) const;
\r
225 /*! \brief Host::getRunningTaskNumber() - returns the number of tasks currently running on a host.
\r
227 * \return The number of task currently running of the host object.
\r
229 * \remark The external load is not taken in account.
\r
231 int getRunningTaskNumber(void) const;
\r
233 /*! \brief Host::getSpeed() - returns the speed of the processor of a host,
\r
234 * regardless of the current load of the machine.
\r
236 * \return The speed of the processor of the host in flops.
\r
238 double getSpeed(void) const;
\r
240 /*! \brief Host::isAvailable - tests if an host is availabled.
\r
242 * \return Is the host is availabled the method returns
\r
243 * 1. Otherwise the method returns 0.
\r
245 int isAvailable(void) const;
\r
247 /* ! \brief Host::put() - put a task on the given channel of a host .
\r
249 * \param channel The channel where to put the task.
\r
250 * \param rTask A refercence to the task object containing the native task to
\r
251 * put on the channel specified by the parameter channel.
\r
253 * \return If successful the task is puted on the specified channel. Otherwise
\r
254 * the method throws one of the exceptions described below.
\r
256 * \exception [MsgException] if an internal error occurs.
\r
257 * [InvalidArgumentException] if the value of the channel specified as
\r
258 * parameter is negative.
\r
260 void put(int channel, Task* task)
\r
261 throw(MsgException, InvalidArgumentException);
\r
263 /* ! \brief Host::put() - put a task on the given channel of a host object (waiting at most timeout seconds).
\r
265 * \param channel The channel where to put the task.
\r
266 * \param rTask A refercence to the task object containing the native task to
\r
267 * put on the channel specified by the parameter channel.
\r
268 * \param timeout The timeout in seconds.
\r
270 * \return If successful the task is puted on the specified channel. Otherwise
\r
271 * the method throws one of the exceptions described below.
\r
273 * \exception [MsgException] if an internal error occurs.
\r
274 * [InvalidArgumentException] if the value of the channel specified as
\r
275 * parameter is negative or if the timeout value
\r
276 * is less than zero and différent of -1.
\r
278 * \remark To specify no timeout set the timeout value with -1.0.
\r
280 void put(int channel, Task* task, double timeout)
\r
281 throw(MsgException, InvalidArgumentException);
\r
283 /* ! \brief Host::putBounded() - put a task on the given channel of a host object (capping the emission rate to maxrate).
\r
285 * \param channel The channel where to put the task.
\r
286 * \param rTask A refercence to the task object containing the native task to
\r
287 * put on the channel specified by the parameter channel.
\r
288 * \param maxRate The maximum rate.
\r
290 * \return If successful the task is puted on the specified channel. Otherwise
\r
291 * the method throws one of the exceptions described below.
\r
293 * \exception [MsgException] if an internal error occurs.
\r
294 * [InvalidArgumentException] if the value of the channel specified as
\r
295 * parameter is negative or if the maxRate parameter value
\r
296 * is less than zero and différent of -1.0.
\r
298 * \remark To specify no rate set the maxRate parameter value with -1.0.
\r
300 void putBounded(int channel, Task* task, double maxRate)
\r
301 throw(MsgException, InvalidArgumentException);
\r
303 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias.
\r
305 * \param rTask A reference to the task object containing the native msg task to send.
\r
307 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
308 * method throws one of the exceptions described below.
\r
310 * \exception [BadAllocException] if there is not enough memory to allocate
\r
311 * the default alias variable.
\r
312 * [MsgException] if an internal error occurs.
\r
314 void send(Task* task)
\r
315 throw(MsgException, BadAllocException);
\r
317 /* ! brief Host::send() - sends the given task to mailbox identified by the specified alias parameter.
\r
319 * \param rTask A reference to the task object containing the native msg task to send.
\r
320 * \param alias The alias of the mailbox where to send the task.
\r
322 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
323 * method throws one of the exceptions described below.
\r
325 * \exception [InvalidArgumentException] if alias parameter is invalid (NULL).
\r
326 * [BadAllocException] if there is not enough memory to allocate
\r
327 * the default alias variable.
\r
328 * [MsgException] if an internal error occurs.
\r
330 void send(const char* alias, Task* task)
\r
331 throw(InvalidArgumentException, MsgException);
\r
333 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias
\r
334 * (waiting at most timeout seconds).
\r
336 * \param rTask A reference to the task object containing the native msg task to send.
\r
337 * \param timeout The timeout value to wait for.
\r
339 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
340 * method throws one of the exceptions described below.
\r
342 * \exception [BadAllocException] if there is not enough memory to allocate
\r
343 * the default alias variable.
\r
344 * [InvalidArgumentException] if the timeout value is negative and different of
\r
346 * [MsgException] if an internal error occurs.
\r
348 * \remark To specify no timeout set the timeout value with -1.0 or use the previous
\r
349 * version of this method.
\r
352 void send(Task* task, double timeout)
\r
353 throw(InvalidArgumentException, BadAllocException, MsgException);
\r
355 /* ! brief Host::send() - sends the given task to mailbox identified by the parameter alias
\r
356 * (waiting at most timeout seconds).
\r
358 * \param alias The alias of the mailbox to send the task.
\r
359 * \param rTask A reference to the task object containing the native msg task to send.
\r
360 * \param timeout The timeout value to wait for.
\r
362 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
363 * method throws one of the exceptions described below.
\r
365 * \exception [InvalidArgumentException] if the timeout value is negative and different of
\r
366 * -1.0 or if the alias parameter is invalid (NULL).
\r
367 * [MsgException] if an internal error occurs.
\r
369 * \remark To specify no timeout set the timeout value with -1.0 or use the previous
\r
370 * version of this method.
\r
373 void send(const char* alias, Task* task, double timeout)
\r
374 throw(InvalidArgumentException, MsgException);
\r
376 /* ! brief Host::sendBounded() - sends the given task to mailbox associated to the default alias
\r
377 * (capping the emission rate to maxRate).
\r
379 * \param rTask A reference to the task object containing the native msg task to send.
\r
380 * \param maxRate The maximum rate value.
\r
382 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
383 * method throws one of the exceptions described below.
\r
385 * \exception [InvalidArgumentException] if the maximum rate value is negative and different of
\r
387 * [MsgException] if an internal error occurs.
\r
388 * [BadAllocException] if there is not enough memory to allocate
\r
389 * the default alias variable.
\r
391 * \remark To specify no rate set its value with -1.0.
\r
394 void sendBounded(Task* task, double maxRate)
\r
395 throw(InvalidArgumentException, BadAllocException, MsgException);
\r
397 /* ! brief Host::sendBounded() - sends the given task to mailbox identified by the parameter alias
\r
398 * (capping the emission rate to maxRate).
\r
400 * \param alias The alias of the mailbox where to send the task.
\r
401 * \param rTask A reference to the task object containing the native msg task to send.
\r
402 * \param maxRate The maximum rate value.
\r
404 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
405 * method throws one of the exceptions described below.
\r
407 * \exception [InvalidArgumentException] if the maximum rate value is negative and different of
\r
408 * -1.0 or if the alias parameter is invalid (NULL).
\r
409 * [MsgException] if an internal error occurs.
\r
411 * \remark To specify no rate set its value with -1.0.
\r
414 void sendBounded(const char* alias, Task* task, double maxRate)
\r
415 throw(InvalidArgumentException, MsgException);
\r
421 * This attribute represents the msg native host object.
\r
422 * It is set automaticatly during the call of the static
\r
423 * method Host::getByName().
\r
425 * \see Host::getByName().
\r
427 m_host_t nativeHost;
\r
436 typedef Host* HostPtr;
\r
438 } // namespace SimGrid
\r
440 #endif // !MSG_HOST_HPP
\r
