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