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
64 // namespace SimGrid::Msg
\r
72 // Declaration of the class SimGrid::Msg::Host.
\r
73 class SIMGRIDX_EXPORT Host // final class.
\r
75 friend class Process;
\r
78 // Desable the default constructor.
\r
79 // The best way to get an host instance is to use the static method Host::getByName().
\r
83 // Default constructor (desabled).
\r
88 // Copy constructor (desabled).
\r
89 Host(const Host& rHost);
\r
91 // Destructor (desable).
\r
96 /*! \brief Host::getByName() - returns an host by its name
\r
98 * This static method returns a reference to the host instance associated
\r
99 * with a native host of your platform. This is the best way to get a host.
\r
101 * \param hostName The name of the host.
\r
103 * \return If successful the method returns a reference to the instance
\r
104 * associated with the native host having the name specified
\r
105 * as parameter of your platform. Otherwise the method throws
\r
106 * one of the exceptions detailed below.
\r
108 * \exception [HostNotFoundException] if no host with the specified name
\r
110 * [InvalidArgumentException] if the hostName parameter is invalid (NULL).
\r
111 * [BadAllocException] if there is not enough memory to allocate the host.
\r
113 static Host& getByName(const char* hostName)
\r
114 throw(HostNotFoundException, NullPointerException, BadAllocException);
\r
116 /*! \brief Host::getNumber() - returns the number of the installed hosts.
\r
118 * \return The number of hosts installed.
\r
120 static int getNumber(void);
\r
123 /*! \brief Host::currentHost() - This static method returns the location on which the current
\r
124 * process is executed.
\r
126 * \return The host of the current process.
\r
128 * \see Process::currentProcess().
\r
130 static Host& currentHost(void);
\r
132 /*! \brief Host::all() - This static method retrieves all of the hosts of the installed platform.
\r
134 * \param hosts A pointer to array of Host pointers that receives all the hosts of the platform.
\r
136 * \param len A pointer to the length of the table of pointers.
\r
138 * \return If successful the hosts table is filled and
\r
139 * the parameter len is set with the number of hosts of the platform.
\r
140 * Otherwise the method throw one of the exception described below.
\r
142 * \exception [InvalidArgumentException] if the parameter hosts is invalid or
\r
143 * if the parameter len is negative or
\r
144 * less than the number of hosts installed
\r
145 * on the current platform.
\r
146 * [BadAllocException] If the method can't allocate memory to fill
\r
147 * the table of hosts.
\r
150 * \remark To get the number of hosts installed on your platform use the static method
\r
151 * Host::getNumber().
\r
153 * \see Host::getNumber().
\r
156 * // This example show how to use this method to get the list of hosts installed on your platform.
\r
158 * using namespace SimGrid::Msg;
\r
161 * // (1) get the number of hosts.
\r
162 * int number = Host::getNumber();
\r
164 * // (2) allocate the array that receives the list of hosts.
\r
165 * HostPtr* ar = new HostPtr[number]; // HostPtr is defined as (typedef Host* HostPtr at the end of the
\r
166 * // declaration of this class.
\r
168 * // (3) call the method
\r
171 * Host::all(&ar, &number);
\r
173 * catch(BadAllocException e)
\r
175 * cerr << e.toString() << endl;
\r
178 * catch(InvalidArgumentException e)
\r
180 * cerr << e.toString() << endl;
\r
184 * // (4) use the table of host (for example print all the name of all the hosts);
\r
186 * for(int i = 0; i < number ; i++)
\r
187 * cout << ar[i]->getName() << endl;
\r
191 * // (5) release the allocate table
\r
196 static void all(Host*** hosts /*in|out*/, int* len /*in|out*/)
\r
197 throw(InvalidArgumentException, BadAllocException) ;
\r
199 /*! \brief Host::getName() - This method return the name of the Msg host object.
\r
201 * \return The name of the host object.
\r
203 const char* getName(void) const;
\r
205 /*! \brief Host::setData() - Set the user data of an host object.
\r
207 * \param data The user data to set.
\r
209 void setData(void* data);
\r
211 /*! \brief Host::getData() - Get the user data of a host object.
\r
213 * \return The user data of the host object.
\r
215 void* getData(void) const;
\r
217 /*! \brief Host::hasData() - Test if an host object has some data.
\r
219 * \return This method returns true if the host object has some user data.
\r
220 * Otherwise the method returns false.
\r
222 bool hasData(void) const;
\r
224 /*! \brief Host::getRunningTaskNumber() - returns the number of tasks currently running on a host.
\r
226 * \return The number of task currently running of the host object.
\r
228 * \remark The external load is not taken in account.
\r
230 int getRunningTaskNumber(void) const;
\r
232 /*! \brief Host::getSpeed() - returns the speed of the processor of a host,
\r
233 * regardless of the current load of the machine.
\r
235 * \return The speed of the processor of the host in flops.
\r
237 double getSpeed(void) const;
\r
239 /*! \brief Host::isAvailable - tests if an host is availabled.
\r
241 * \return Is the host is availabled the method returns
\r
242 * 1. Otherwise the method returns 0.
\r
244 int isAvailable(void) const;
\r
246 /* ! \brief Host::put() - put a task on the given channel of a host .
\r
248 * \param channel The channel where to put the task.
\r
249 * \param rTask A refercence to the task object containing the native task to
\r
250 * put on the channel specified by the parameter channel.
\r
252 * \return If successful the task is puted on the specified channel. Otherwise
\r
253 * the method throws one of the exceptions described below.
\r
255 * \exception [MsgException] if an internal error occurs.
\r
256 * [InvalidArgumentException] if the value of the channel specified as
\r
257 * parameter is negative.
\r
259 void put(int channel, Task* task)
\r
260 throw(MsgException, InvalidArgumentException);
\r
262 /* ! \brief Host::put() - put a task on the given channel of a host object (waiting at most timeout seconds).
\r
264 * \param channel The channel where to put the task.
\r
265 * \param rTask A refercence to the task object containing the native task to
\r
266 * put on the channel specified by the parameter channel.
\r
267 * \param timeout The timeout in seconds.
\r
269 * \return If successful the task is puted on the specified channel. Otherwise
\r
270 * the method throws one of the exceptions described below.
\r
272 * \exception [MsgException] if an internal error occurs.
\r
273 * [InvalidArgumentException] if the value of the channel specified as
\r
274 * parameter is negative or if the timeout value
\r
275 * is less than zero and différent of -1.
\r
277 * \remark To specify no timeout set the timeout value with -1.0.
\r
279 void put(int channel, Task* task, double timeout)
\r
280 throw(MsgException, InvalidArgumentException);
\r
282 /* ! \brief Host::putBounded() - put a task on the given channel of a host object (capping the emission rate to maxrate).
\r
284 * \param channel The channel where to put the task.
\r
285 * \param rTask A refercence to the task object containing the native task to
\r
286 * put on the channel specified by the parameter channel.
\r
287 * \param maxRate The maximum rate.
\r
289 * \return If successful the task is puted on the specified channel. Otherwise
\r
290 * the method throws one of the exceptions described below.
\r
292 * \exception [MsgException] if an internal error occurs.
\r
293 * [InvalidArgumentException] if the value of the channel specified as
\r
294 * parameter is negative or if the maxRate parameter value
\r
295 * is less than zero and différent of -1.0.
\r
297 * \remark To specify no rate set the maxRate parameter value with -1.0.
\r
299 void putBounded(int channel, Task* task, double maxRate)
\r
300 throw(MsgException, InvalidArgumentException);
\r
302 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias.
\r
304 * \param rTask A reference to the task object containing the native msg task to send.
\r
306 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
307 * method throws one of the exceptions described below.
\r
309 * \exception [BadAllocException] if there is not enough memory to allocate
\r
310 * the default alias variable.
\r
311 * [MsgException] if an internal error occurs.
\r
313 void send(Task* task)
\r
314 throw(MsgException, BadAllocException);
\r
316 /* ! brief Host::send() - sends the given task to mailbox identified by the specified alias parameter.
\r
318 * \param rTask A reference to the task object containing the native msg task to send.
\r
319 * \param alias The alias of the mailbox where to send the task.
\r
321 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
322 * method throws one of the exceptions described below.
\r
324 * \exception [InvalidArgumentException] if alias parameter is invalid (NULL).
\r
325 * [BadAllocException] if there is not enough memory to allocate
\r
326 * the default alias variable.
\r
327 * [MsgException] if an internal error occurs.
\r
329 void send(const char* alias, Task* task)
\r
330 throw(InvalidArgumentException, MsgException);
\r
332 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias
\r
333 * (waiting at most timeout seconds).
\r
335 * \param rTask A reference to the task object containing the native msg task to send.
\r
336 * \param timeout The timeout value to wait for.
\r
338 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
339 * method throws one of the exceptions described below.
\r
341 * \exception [BadAllocException] if there is not enough memory to allocate
\r
342 * the default alias variable.
\r
343 * [InvalidArgumentException] if the timeout value is negative and different of
\r
345 * [MsgException] if an internal error occurs.
\r
347 * \remark To specify no timeout set the timeout value with -1.0 or use the previous
\r
348 * version of this method.
\r
351 void send(Task* task, double timeout)
\r
352 throw(InvalidArgumentException, BadAllocException, MsgException);
\r
354 /* ! brief Host::send() - sends the given task to mailbox identified by the parameter alias
\r
355 * (waiting at most timeout seconds).
\r
357 * \param alias The alias of the mailbox to send the task.
\r
358 * \param rTask A reference to the task object containing the native msg task to send.
\r
359 * \param timeout The timeout value to wait for.
\r
361 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
362 * method throws one of the exceptions described below.
\r
364 * \exception [InvalidArgumentException] if the timeout value is negative and different of
\r
365 * -1.0 or if the alias parameter is invalid (NULL).
\r
366 * [MsgException] if an internal error occurs.
\r
368 * \remark To specify no timeout set the timeout value with -1.0 or use the previous
\r
369 * version of this method.
\r
372 void send(const char* alias, Task* task, double timeout)
\r
373 throw(InvalidArgumentException, MsgException);
\r
375 /* ! brief Host::sendBounded() - sends the given task to mailbox associated to the default alias
\r
376 * (capping the emission rate to maxRate).
\r
378 * \param rTask A reference to the task object containing the native msg task to send.
\r
379 * \param maxRate The maximum rate value.
\r
381 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
382 * method throws one of the exceptions described below.
\r
384 * \exception [InvalidArgumentException] if the maximum rate value is negative and different of
\r
386 * [MsgException] if an internal error occurs.
\r
387 * [BadAllocException] if there is not enough memory to allocate
\r
388 * the default alias variable.
\r
390 * \remark To specify no rate set its value with -1.0.
\r
393 void sendBounded(Task* task, double maxRate)
\r
394 throw(InvalidArgumentException, BadAllocException, MsgException);
\r
396 /* ! brief Host::sendBounded() - sends the given task to mailbox identified by the parameter alias
\r
397 * (capping the emission rate to maxRate).
\r
399 * \param alias The alias of the mailbox where to send the task.
\r
400 * \param rTask A reference to the task object containing the native msg task to send.
\r
401 * \param maxRate The maximum rate value.
\r
403 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
404 * method throws one of the exceptions described below.
\r
406 * \exception [InvalidArgumentException] if the maximum rate value is negative and different of
\r
407 * -1.0 or if the alias parameter is invalid (NULL).
\r
408 * [MsgException] if an internal error occurs.
\r
410 * \remark To specify no rate set its value with -1.0.
\r
413 void sendBounded(const char* alias, Task* task, double maxRate)
\r
414 throw(InvalidArgumentException, MsgException);
\r
420 * This attribute represents the msg native host object.
\r
421 * It is set automaticatly during the call of the static
\r
422 * method Host::getByName().
\r
424 * \see Host::getByName().
\r
426 m_host_t nativeHost;
\r
435 typedef Host* HostPtr;
\r
437 } // namespace SimGrid
\r
439 #endif // !MSG_HOST_HPP
\r
