src/cxx/Host.hpp

   1 /*\r
   2  * Host.hpp\r
   3  *\r
   4  * Copyright 2006,2007 Martin Quinson, Malek Cherier           \r
   5  * All right reserved. \r
   6  *\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
  10  *\r
  11  */  \r
  12 #ifndef MSG_HOST_HPP\r
  13 #define MSG_HOST_HPP\r
  14 \r
  15 \r
  16 /*! \brief Host class declaration.\r
  17  *\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
  26  *\r
  27  * The best way to get an host is to call the static method \r
  28  * Host.getByName() which returns a reference.\r
  29  *\r
  30  * For example to get the instance of the host. If your platform\r
  31  * file description contains an host named "Jacquelin" :\r
  32  *\r
  33  * \verbatim\r
  34 using namespace SimGrid.Msg;\r
  35 \r
  36 Host jacquelin;\r
  37 \r
  38 try \r
  39 { \r
  40         jacquelin = Host::getByName("Jacquelin");\r
  41 }\r
  42 catch(HostNotFoundException e) \r
  43 {\r
  44         cerr << e.toString();\r
  45 }\r
  46 ...\r
  47 \endverbatim\r
  48  *\r
  49  */\r
  50 \r
  51 #ifndef __cplusplus\r
  52         #error Host.hpp requires C++ compilation (use a .cxx suffix)\r
  53 #endif\r
  54 \r
  55 #include <InvalidArgumentException.hpp>\r
  56 #include <BadAllocException.hpp>\r
  57 #include <HostNotFoundException.hpp>\r
  58 #include <MsgException.hpp>\r
  59 \r
  60 // namespace SimGrid::Msg\r
  61 namespace SimGrid\r
  62 {\r
  63         namespace Msg\r
  64         {\r
  65                 // Declaration of the class SimGrid::Msg::Host.\r
  66                 class Host // final class.\r
  67                 {\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
  70                         \r
  71                         private :\r
  72                                 \r
  73                         // Default constructor (desabled).\r
  74                                 Host();\r
  75                         \r
  76                         public: \r
  77                                 \r
  78                         // Copy constructor (desabled).\r
  79                                 Host(const Host& rHost);\r
  80                                 \r
  81                         // Destructor (desable).\r
  82                                 virtual ~Host();\r
  83                         \r
  84                         // Operations\r
  85                         \r
  86                                 /*! \brief Host::getByName() - returns an host by its name\r
  87                                  *\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
  90                                  *\r
  91                                  * \param hostName      The name of the host.\r
  92                                  *\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
  97                                  *\r
  98                                  * \exception           [HostNotFoundException]         if no host with the specified name\r
  99                                  *                                                                                              was found.\r
 100                                  *                                      [InvalidParameterException]     if the hostName parameter is invalid (NULL).\r
 101                                  *                                      [BadAllocException]                     if there is not enough memory to allocate the host.\r
 102                                  */ \r
 103                                 static Host& getByName(const char* hostName)\r
 104                                 throw(HostNotFoundException, InvalidParameterException, BadAllocException);\r
 105                                 \r
 106                                 /*! \brief Host::getNumber() - returns the number of the installed hosts.\r
 107                                  *\r
 108                                  * \return                      The number of hosts installed.\r
 109                                  */\r
 110                                 static int getNumber(void);\r
 111                                 \r
 112                                 \r
 113                                 /*! \brief Host::currentHost() - This static method returns the location on which the current \r
 114                                  * process is executed.\r
 115                                  *\r
 116                                  * \return                      The host of the current process.\r
 117                                  *\r
 118                                  * \see                         Process::currentProcess().\r
 119                                  */\r
 120                                 static Host& currentHost(void)\r
 121                                 throw(InvalidParameterException, BadAllocException);\r
 122                                 \r
 123                                 /*! \brief Host::all() - This static method retrieves all of the hosts of the installed platform.\r
 124                                  *\r
 125                                  * \param hosts         A pointer to array of Host pointers that receives all the hosts of the platform.\r
 126                                  *\r
 127                                  * \param len           A pointer to the length of the table of pointers.\r
 128                                  *\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
 132                                  *\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
 139                                  *\r
 140                                  *\r
 141                                  * \remark                      To get the number of hosts installed on your platform use the static method\r
 142                                  *                                      Host::getNumber().\r
 143                                  *\r
 144                                  * \see                         Host::getNumber().\r
 145                                  *\r
 146                                  *\verbatim\r
 147                                  * // This example show how to use this method to get the list of hosts installed on your platform.\r
 148                                  *\r
 149                                  *      using namespace SimGrid::Msg;\r
 150                                  *      using <iostream>\r
 151                                  *\r
 152                                  *      // (1) get the number of hosts.\r
 153                                  *      int number = Host::getNumber();\r
 154                                  *      \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
 158                                  *\r
 159                                  *      // (3) call the method\r
 160                                  *      try\r
 161                                  *      {\r
 162                                  *              Host::all(&ar, &number);\r
 163                                  *      }\r
 164                                  *      catch(BadAllocException e)\r
 165                                  *      {\r
 166                                  *              cerr << e.toString() << endl;\r
 167                                  *              ...\r
 168                                  *      }\r
 169                                  *      catch(InvalidArgumentException e)\r
 170                                  *      {\r
 171                                  *              cerr << e.toString() << endl;\r
 172                                  *              ..\r
 173                                  *      } \r
 174                                  *\r
 175                                  *      // (4) use the table of host (for example print all the name of all the hosts);\r
 176                                  *      \r
 177                                  *      for(int i = 0; i < number ; i++)\r
 178                                  *              cout << ar[i]->getName() << endl;\r
 179                                  *\r
 180                                  *      ...\r
 181                                  *              \r
 182                                  *      // (5) release the allocate table\r
 183                                  *      \r
 184                                  *      delete[] ar;\r
 185                                  *\r
 186                                  */ \r
 187                                 static void all(Host*** hosts /*in|out*/, int* len /*in|out*/);\r
 188                                 \r
 189                                 /*! \brief Host::getName() - This method return the name of the Msg host object.\r
 190                                  *\r
 191                                  * \return                      The name of the host object.\r
 192                                  */\r
 193                                 const char* getName(void) const;\r
 194                                 \r
 195                                 /*! \brief Host::setData() - Set the user data of an host object.\r
 196                                  *\r
 197                                  * \param data          The user data to set.\r
 198                                  */\r
 199                                 void setData(void* data);\r
 200                                 \r
 201                                 /*! \brief Host::getData() - Get the user data of a host object.\r
 202                                  *\r
 203                                  * \return                      The user data of the host object.\r
 204                                  */\r
 205                                 void* getData(void) const;\r
 206                                 \r
 207                                 /*! \brief Host::hasData() - Test if an host object has some data.\r
 208                                  *\r
 209                                  * \return                      This method returns true if the host object has some user data.\r
 210                                  *                                      Otherwise the method returns false.\r
 211                                  */\r
 212                                 bool hasData(void) const;\r
 213                                 \r
 214                                 /*! \brief Host::getRunningTaskNumber() - returns the number of tasks currently running on a host.\r
 215                                  *\r
 216                                  * \return                      The number of task currently running of the host object.\r
 217                                  *\r
 218                                  * \remark                      The external load is not taken in account.\r
 219                                  */\r
 220                                 int getRunningTaskNumber(void) const;\r
 221                                 \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
 224                                  *\r
 225                                  * \return                      The speed of the processor of the host in flops.\r
 226                                  */ \r
 227                                 double getSpeed(void) const;\r
 228                                 \r
 229                                 /*! \brief Host::isAvailable - tests if an host is availabled.\r
 230                                  * \r
 231                                  * \return                      Is the host is availabled the method returns\r
 232                                  *                                      true. Otherwise the method returns false.\r
 233                                  */ \r
 234                                 bool isAvailble(void) const;\r
 235                                 \r
 236                                 /* ! \brief Host::put() - put a task on the given channel of a host .\r
 237                                  *\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
 241                                  *\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
 244                                  *\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
 248                                  */\r
 249                                 void put(int channel, const Task& rTask)\r
 250                                 throw(MsgException, InvalidParameterException);\r
 251                                 \r
 252                                 /* ! \brief Host::put() - put a task on the given channel of a host object (waiting at most timeout seconds).\r
 253                                  *\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
 258                                  *\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
 261                                  *\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
 266                                  *\r
 267                                  * \remark                      To specify no timeout set the timeout value with -1.0.\r
 268                                  */\r
 269                                 void put(int channel, Task task, double timeout) \r
 270                                 throw(MsgException, InvalidParameterException);\r
 271                                 \r
 272                                 /* ! \brief Host::putBounded() - put a task on the given channel of a host object (capping the emission rate to maxrate).\r
 273                                  *\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
 278                                  *\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
 281                                  *\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
 286                                  *\r
 287                                  * \remark                      To specify no rate set the maxRate parameter value with -1.0.\r
 288                                  */\r
 289                                 void putBounded(int channel, const Task& rTask, double maxRate) \r
 290                                 throw(MsgException, InvalidParameterException);\r
 291                                 \r
 292                                 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias.\r
 293                                  *\r
 294                                  * \param rTask         A reference to the task object containing the native msg task to send.\r
 295                                  *\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
 298                                  *\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
 302                                  */\r
 303                                 void send(const Task& rTask) \r
 304                                 throw(BadAllocException, MsgException);\r
 305                                 \r
 306                                 /* ! brief Host::send() - sends the given task to mailbox identified by the specified alias parameter.\r
 307                                  *\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
 310                                  *\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
 313                                  *\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
 318                                  */\r
 319                                 void send(const char* alias, const Task& rTask) \r
 320                                 throw(InvalidParameterException, BadAllocException, MsgException);\r
 321                                 \r
 322                                 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias\r
 323                                  *  (waiting at most timeout seconds).\r
 324                                  *\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
 327                                  *\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
 330                                  *\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
 334                                  *                                                                                              -1.0.                   \r
 335                                  *                                      [MsgException]                          if an internal error occurs.\r
 336                                  *\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
 339                                  *\r
 340                                  */\r
 341                                 void send(const Task& rTask, double timeout) \r
 342                                 throw(NativeException);\r
 343                                 \r
 344                                 /* ! brief Host::send() - sends the given task to mailbox identified by the parameter alias\r
 345                                  *  (waiting at most timeout seconds).\r
 346                                  *\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
 350                                  *\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
 353                                  *\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
 357                                  *\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
 360                                  *\r
 361                                  */\r
 362                                 void send(const char* alias, const Task& rTask, double timeout) \r
 363                                 throw(InvalidParameterException, MsgException);\r
 364                                 \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
 367                                  *\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
 370                                  *\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
 373                                  *\r
 374                                  * \exception           [InvalidParameterException]     if the maximum rate value is negative and different of\r
 375                                  *                                                                                              -1.0.                   \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
 379                                  *\r
 380                                  * \remark                      To specify no rate set its value with -1.0.\r
 381                                  *\r
 382                                  */\r
 383                                 void sendBounded(const Task& rTask, double maxRate) \r
 384                                 throw(InvalidParameterException, BadAllocException, MsgException);\r
 385                                 \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
 388                                  *\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
 392                                  *\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
 395                                  *\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
 399                                  *\r
 400                                  * \remark                      To specify no rate set its value with -1.0.\r
 401                                  *\r
 402                                  */\r
 403                                 void sendBounded(const char* alias, const Task& rTask, double maxRate) \r
 404                                 throw(InvalidParameterException, MsgException);\r
 405                         \r
 406                         protected:\r
 407                         // Attributes.\r
 408                         \r
 409                                 /**\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
 413                                  *\r
 414                                  * \see                         Host::getByName().\r
 415                                  */ \r
 416                                 m_host_t nativeHost;\r
 417                         \r
 418                         private:\r
 419                                 /**\r
 420                                  * User host data. \r
 421                                  */ \r
 422                                 void* data;\r
 423                 };\r
 424                 \r
 425                 typedef Host* HostPtr;\r
 426         } // namespace Msg\r
 427 } // namespace SimGrid\r
 428 \r
 429 #endif // !MSG_HOST_HPP