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 <InvalidArgumentException.hpp>
\r
56 #include <BadAllocException.hpp>
\r
57 #include <HostNotFoundException.hpp>
\r
58 #include <MsgException.hpp>
\r
60 // namespace SimGrid::Msg
\r
65 // Declaration of the class SimGrid::Msg::Host.
\r
66 class Host // final class.
\r
68 // Desable the default constructor.
\r
69 // The best way to get an host instance is to use the static method Host::getByName().
\r
73 // Default constructor (desabled).
\r
78 // Copy constructor (desabled).
\r
79 Host(const Host& rHost);
\r
81 // Destructor (desable).
\r
86 /*! \brief Host::getByName() - returns an host by its name
\r
88 * This static method returns a reference to the host instance associated
\r
89 * with a native host of your platform. This is the best way to get a host.
\r
91 * \param hostName The name of the host.
\r
93 * \return If successful the method returns a reference to the instance
\r
94 * associated with the native host having the name specified
\r
95 * as parameter of your platform. Otherwise the method throws
\r
96 * one of the exceptions detailed below.
\r
98 * \exception [HostNotFoundException] if no host with the specified name
\r
100 * [InvalidParameterException] if the hostName parameter is invalid (NULL).
\r
101 * [BadAllocException] if there is not enough memory to allocate the host.
\r
103 static Host& getByName(const char* hostName)
\r
104 throw(HostNotFoundException, InvalidParameterException, BadAllocException);
\r
106 /*! \brief Host::getNumber() - returns the number of the installed hosts.
\r
108 * \return The number of hosts installed.
\r
110 static int getNumber(void);
\r
113 /*! \brief Host::currentHost() - This static method returns the location on which the current
\r
114 * process is executed.
\r
116 * \return The host of the current process.
\r
118 * \see Process::currentProcess().
\r
120 static Host& currentHost(void)
\r
121 throw(InvalidParameterException, BadAllocException);
\r
123 /*! \brief Host::all() - This static method retrieves all of the hosts of the installed platform.
\r
125 * \param hosts A pointer to array of Host pointers that receives all the hosts of the platform.
\r
127 * \param len A pointer to the length of the table of pointers.
\r
129 * \return If successful the hosts table is filled and
\r
130 * the parameter len is set with the number of hosts of the platform.
\r
131 * Otherwise the method throw one of the exception described below.
\r
133 * \exception [InvalidParameterException] if the parameter hosts is invalid or
\r
134 * if the parameter len is negative or
\r
135 * less than the number of hosts installed
\r
136 * on the current platform.
\r
137 * [BadAllocException] If the method can't allocate memory to fill
\r
138 * the table of hosts.
\r
141 * \remark To get the number of hosts installed on your platform use the static method
\r
142 * Host::getNumber().
\r
144 * \see Host::getNumber().
\r
147 * // This example show how to use this method to get the list of hosts installed on your platform.
\r
149 * using namespace SimGrid::Msg;
\r
152 * // (1) get the number of hosts.
\r
153 * int number = Host::getNumber();
\r
155 * // (2) allocate the array that receives the list of hosts.
\r
156 * HostPtr* ar = new HostPtr[number]; // HostPtr is defined as (typedef Host* HostPtr at the end of the
\r
157 * // declaration of this class.
\r
159 * // (3) call the method
\r
162 * Host::all(&ar, &number);
\r
164 * catch(BadAllocException e)
\r
166 * cerr << e.toString() << endl;
\r
169 * catch(InvalidArgumentException e)
\r
171 * cerr << e.toString() << endl;
\r
175 * // (4) use the table of host (for example print all the name of all the hosts);
\r
177 * for(int i = 0; i < number ; i++)
\r
178 * cout << ar[i]->getName() << endl;
\r
182 * // (5) release the allocate table
\r
187 static void all(Host*** hosts /*in|out*/, int* len /*in|out*/);
\r
189 /*! \brief Host::getName() - This method return the name of the Msg host object.
\r
191 * \return The name of the host object.
\r
193 const char* getName(void) const;
\r
195 /*! \brief Host::setData() - Set the user data of an host object.
\r
197 * \param data The user data to set.
\r
199 void setData(void* data);
\r
201 /*! \brief Host::getData() - Get the user data of a host object.
\r
203 * \return The user data of the host object.
\r
205 void* getData(void) const;
\r
207 /*! \brief Host::hasData() - Test if an host object has some data.
\r
209 * \return This method returns true if the host object has some user data.
\r
210 * Otherwise the method returns false.
\r
212 bool hasData(void) const;
\r
214 /*! \brief Host::getRunningTaskNumber() - returns the number of tasks currently running on a host.
\r
216 * \return The number of task currently running of the host object.
\r
218 * \remark The external load is not taken in account.
\r
220 int getRunningTaskNumber(void) const;
\r
222 /*! \brief Host::getSpeed() - returns the speed of the processor of a host,
\r
223 * regardless of the current load of the machine.
\r
225 * \return The speed of the processor of the host in flops.
\r
227 double getSpeed(void) const;
\r
229 /*! \brief Host::isAvailable - tests if an host is availabled.
\r
231 * \return Is the host is availabled the method returns
\r
232 * true. Otherwise the method returns false.
\r
234 bool isAvailble(void) const;
\r
236 /* ! \brief Host::put() - put a task on the given channel of a host .
\r
238 * \param channel The channel where to put the task.
\r
239 * \param rTask A refercence to the task object containing the native task to
\r
240 * put on the channel specified by the parameter channel.
\r
242 * \return If successful the task is puted on the specified channel. Otherwise
\r
243 * the method throws one of the exceptions described below.
\r
245 * \exception [MsgException] if an internal error occurs.
\r
246 * [InvalidParameterException] if the value of the channel specified as
\r
247 * parameter is negative.
\r
249 void put(int channel, const Task& rTask)
\r
250 throw(MsgException, InvalidParameterException);
\r
252 /* ! \brief Host::put() - put a task on the given channel of a host object (waiting at most timeout seconds).
\r
254 * \param channel The channel where to put the task.
\r
255 * \param rTask A refercence to the task object containing the native task to
\r
256 * put on the channel specified by the parameter channel.
\r
257 * \param timeout The timeout in seconds.
\r
259 * \return If successful the task is puted on the specified channel. Otherwise
\r
260 * the method throws one of the exceptions described below.
\r
262 * \exception [MsgException] if an internal error occurs.
\r
263 * [InvalidParameterException] if the value of the channel specified as
\r
264 * parameter is negative or if the timeout value
\r
265 * is less than zero and différent of -1.
\r
267 * \remark To specify no timeout set the timeout value with -1.0.
\r
269 void put(int channel, Task task, double timeout)
\r
270 throw(MsgException, InvalidParameterException);
\r
272 /* ! \brief Host::putBounded() - put a task on the given channel of a host object (capping the emission rate to maxrate).
\r
274 * \param channel The channel where to put the task.
\r
275 * \param rTask A refercence to the task object containing the native task to
\r
276 * put on the channel specified by the parameter channel.
\r
277 * \param maxRate The maximum rate.
\r
279 * \return If successful the task is puted on the specified channel. Otherwise
\r
280 * the method throws one of the exceptions described below.
\r
282 * \exception [MsgException] if an internal error occurs.
\r
283 * [InvalidParameterException] if the value of the channel specified as
\r
284 * parameter is negative or if the maxRate parameter value
\r
285 * is less than zero and différent of -1.0.
\r
287 * \remark To specify no rate set the maxRate parameter value with -1.0.
\r
289 void putBounded(int channel, const Task& rTask, double maxRate)
\r
290 throw(MsgException, InvalidParameterException);
\r
292 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias.
\r
294 * \param rTask A reference to the task object containing the native msg task to send.
\r
296 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
297 * method throws one of the exceptions described below.
\r
299 * \exception [BadAllocException] if there is not enough memory to allocate
\r
300 * the default alias variable.
\r
301 * [MsgException] if an internal error occurs.
\r
303 void send(const Task& rTask)
\r
304 throw(BadAllocException, MsgException);
\r
306 /* ! brief Host::send() - sends the given task to mailbox identified by the specified alias parameter.
\r
308 * \param rTask A reference to the task object containing the native msg task to send.
\r
309 * \param alias The alias of the mailbox where to send the task.
\r
311 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
312 * method throws one of the exceptions described below.
\r
314 * \exception [InvalidParameterException] if alias parameter is invalid (NULL).
\r
315 * [BadAllocException] if there is not enough memory to allocate
\r
316 * the default alias variable.
\r
317 * [MsgException] if an internal error occurs.
\r
319 void send(const char* alias, const Task& rTask)
\r
320 throw(InvalidParameterException, BadAllocException, MsgException);
\r
322 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias
\r
323 * (waiting at most timeout seconds).
\r
325 * \param rTask A reference to the task object containing the native msg task to send.
\r
326 * \param timeout The timeout value to wait for.
\r
328 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
329 * method throws one of the exceptions described below.
\r
331 * \exception [BadAllocException] if there is not enough memory to allocate
\r
332 * the default alias variable.
\r
333 * [InvalidParameterException] if the timeout value is negative and different of
\r
335 * [MsgException] if an internal error occurs.
\r
337 * \remark To specify no timeout set the timeout value with -1.0 or use the previous
\r
338 * version of this method.
\r
341 void send(const Task& rTask, double timeout)
\r
342 throw(NativeException);
\r
344 /* ! brief Host::send() - sends the given task to mailbox identified by the parameter alias
\r
345 * (waiting at most timeout seconds).
\r
347 * \param alias The alias of the mailbox to send the task.
\r
348 * \param rTask A reference to the task object containing the native msg task to send.
\r
349 * \param timeout The timeout value to wait for.
\r
351 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
352 * method throws one of the exceptions described below.
\r
354 * \exception [InvalidParameterException] if the timeout value is negative and different of
\r
355 * -1.0 or if the alias parameter is invalid (NULL).
\r
356 * [MsgException] if an internal error occurs.
\r
358 * \remark To specify no timeout set the timeout value with -1.0 or use the previous
\r
359 * version of this method.
\r
362 void send(const char* alias, const Task& rTask, double timeout)
\r
363 throw(InvalidParameterException, MsgException);
\r
365 /* ! brief Host::sendBounded() - sends the given task to mailbox associated to the default alias
\r
366 * (capping the emission rate to maxRate).
\r
368 * \param rTask A reference to the task object containing the native msg task to send.
\r
369 * \param maxRate The maximum rate value.
\r
371 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
372 * method throws one of the exceptions described below.
\r
374 * \exception [InvalidParameterException] if the maximum rate value is negative and different of
\r
376 * [MsgException] if an internal error occurs.
\r
377 * [BadAllocException] if there is not enough memory to allocate
\r
378 * the default alias variable.
\r
380 * \remark To specify no rate set its value with -1.0.
\r
383 void sendBounded(const Task& rTask, double maxRate)
\r
384 throw(InvalidParameterException, BadAllocException, MsgException);
\r
386 /* ! brief Host::sendBounded() - sends the given task to mailbox identified by the parameter alias
\r
387 * (capping the emission rate to maxRate).
\r
389 * \param alias The alias of the mailbox where to send the task.
\r
390 * \param rTask A reference to the task object containing the native msg task to send.
\r
391 * \param maxRate The maximum rate value.
\r
393 * \return If successful the task is sended to the default mailbox. Otherwise the
\r
394 * method throws one of the exceptions described below.
\r
396 * \exception [InvalidParameterException] if the maximum rate value is negative and different of
\r
397 * -1.0 or if the alias parameter is invalid (NULL).
\r
398 * [MsgException] if an internal error occurs.
\r
400 * \remark To specify no rate set its value with -1.0.
\r
403 void sendBounded(const char* alias, const Task& rTask, double maxRate)
\r
404 throw(InvalidParameterException, MsgException);
\r
410 * This attribute represents the msg native host object.
\r
411 * It is set automaticatly during the call of the static
\r
412 * method Host::getByName().
\r
414 * \see Host::getByName().
\r
416 m_host_t nativeHost;
\r
425 typedef Host* HostPtr;
\r
427 } // namespace SimGrid
\r
429 #endif // !MSG_HOST_HPP