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 \r
  59 // namespace SimGrid::Msg\r
  60 namespace SimGrid\r
  61 {\r
  62         namespace Msg\r
  63         {\r
  64                 // Declaration of the class SimGrid::Msg::Host.\r
  65                 class Host\r
  66                 {\r
  67                         // Desable the default constructor.\r
  68                         // The best way to get an host instance is to use the static method Host::getByName().\r
  69                         \r
  70                         private :\r
  71                                 \r
  72                         // Default constructor (desabled).\r
  73                                 Host();\r
  74                         \r
  75                         public: \r
  76                                 \r
  77                         // Copy constructor (desabled).\r
  78                                 Host(const Host& rHost);\r
  79                                 \r
  80                         // Destructor (desable).\r
  81                                 virtual ~Host();\r
  82                         \r
  83                         // Operations\r
  84                         \r
  85                                 /*! \brief Host::getByName() - returns an host by its name\r
  86                                  *\r
  87                                  * This static method returns a reference to the host instance associated \r
  88                                  * with a native host of your platform. This is the best way to get a host.\r
  89                                  *\r
  90                                  * \param hostName      The name of the host.\r
  91                                  *\r
  92                                  * \return                      If successful the method returns a reference to the instance\r
  93                                  *                                      associated with the native host having the name specified\r
  94                                  *                                      as parameter of your platform. Otherwise the method throws\r
  95                                  *                                      one of the exceptions detailed below.\r
  96                                  *\r
  97                                  * \exception           [HostNotFoundException]         if no host with the specified name\r
  98                                  *                                                                                              was found.\r
  99                                  *                                      [InvalidParameterException]     if the hostName parameter is invalid (NULL).\r
 100                                  *                                      [BadAllocException]                     if there is not enough memory to allocate the host.\r
 101                                  */ \r
 102                                 static Host& getByName(const char* hostName)\r
 103                                 throw(HostNotFoundException, InvalidParameterException, BadAllocException);\r
 104                                 \r
 105                                 /*! \brief Host::getNumber() - returns the number of the installed hosts.\r
 106                                  *\r
 107                                  * \return                      The number of hosts installed.\r
 108                                  */\r
 109                                 static int getNumber(void);\r
 110                                 \r
 111                                 \r
 112                                 /*! \brief Host::currentHost() - This static method returns the location on which the current \r
 113                                  * process is executed.\r
 114                                  *\r
 115                                  * \return                      The host of the current process.\r
 116                                  *\r
 117                                  * \see                         Process::currentProcess().\r
 118                                  */\r
 119                                 static Host& currentHost(void)\r
 120                                 throw(InvalidParameterException, BadAllocException);\r
 121                                 \r
 122                                 /*! \brief Host::all() - This static method retrieves all of the hosts of the installed platform.\r
 123                                  *\r
 124                                  * \param hosts         A pointer to array of Host pointers that receives all the hosts of the platform.\r
 125                                  *\r
 126                                  * \param len           A pointer to the length of the table of pointers.\r
 127                                  *\r
 128                                  * \return                      If successful the hosts table is filled and\r
 129                                  *                                      the parameter len is set with the number of hosts of the platform.\r
 130                                  *                                      Otherwise the method throw one of the exception described below.\r
 131                                  *\r
 132                                  * \exception           [InvalidParameterException]     if the parameter hosts is invalid or\r
 133                                  *                                                                                              if the parameter len is negative or\r
 134                                  *                                                                                              less than the number of hosts installed\r
 135                                  *                                                                                              on the current platform.\r
 136                                  *                                      [BadAllocException]                     If the method can't allocate memory to fill\r
 137                                  *                                                                                              the table of hosts.\r
 138                                  *\r
 139                                  *\r
 140                                  * \remark                      To get the number of hosts installed on your platform use the static method\r
 141                                  *                                      Host::getNumber().\r
 142                                  *\r
 143                                  * \see                         Host::getNumber().\r
 144                                  *\r
 145                                  *\verbatim\r
 146                                  * // This example show how to use this method to get the list of hosts installed on your platform.\r
 147                                  *\r
 148                                  *      using namespace SimGrid::Msg;\r
 149                                  *      using <iostream>\r
 150                                  *\r
 151                                  *      // (1) get the number of hosts.\r
 152                                  *      int number = Host::getNumber();\r
 153                                  *      \r
 154                                  *      // (2) allocate the array that receives the list of hosts.\r
 155                                  *      HostPtr* ar = new HostPtr[number];      // HostPtr is defined as (typedef Host* HostPtr at the end of the\r
 156                                  *                                                                              // declaration of this class.\r
 157                                  *\r
 158                                  *      // (3) call the method\r
 159                                  *      try\r
 160                                  *      {\r
 161                                  *              Host::all(&ar, &number);\r
 162                                  *      }\r
 163                                  *      catch(BadAllocException e)\r
 164                                  *      {\r
 165                                  *              cerr << e.toString() << endl;\r
 166                                  *              ...\r
 167                                  *      }\r
 168                                  *      catch(InvalidArgumentException e)\r
 169                                  *      {\r
 170                                  *              cerr << e.toString() << endl;\r
 171                                  *              ..\r
 172                                  *      } \r
 173                                  *\r
 174                                  *      // (4) use the table of host (for example print all the name of all the hosts);\r
 175                                  *      \r
 176                                  *      for(int i = 0; i < number ; i++)\r
 177                                  *              cout << ar[i]->getName() << endl;\r
 178                                  *\r
 179                                  *      ...\r
 180                                  *              \r
 181                                  *      // (5) release the allocate table\r
 182                                  *      \r
 183                                  *      delete[] ar;\r
 184                                  *\r
 185                                  */ \r
 186                                 static void all(Host*** hosts /*in|out*/, int* len /*in|out*/);\r
 187                                 \r
 188                                 \r
 189                                 const char* getName(void) const;\r
 190                                 \r
 191                                 void setData(void* data);\r
 192                                 \r
 193                                 // Getters/setters\r
 194                                 \r
 195                                 void* getData(void) const;\r
 196                                 \r
 197                                 int Host::getRunningTaskNumber(void) const;\r
 198                                 \r
 199                                 double getSpeed(void) const;\r
 200                                 \r
 201                                 bool hasData(void) const;\r
 202                                 \r
 203                                 bool isAvailble(void) const;\r
 204                                 \r
 205                                 void put(int channel, const Task& rTask)\r
 206                                 throw(NativeException);\r
 207                                 \r
 208                                 void put(int channel, Task task, double timeout) \r
 209                                 throw(NativeException);\r
 210                                 \r
 211                                 void Host::putBounded(int channel, const Task& rTask, double maxRate) \r
 212                                 throw(NativeException);\r
 213                                 \r
 214                                 \r
 215                                 void send(const Task& rTask) \r
 216                                 throw(NativeException);\r
 217                                 \r
 218                                 void send(const char* alias, const Task& rTask) \r
 219                                 throw(NativeException);\r
 220                                 \r
 221                                 void send(const Task& rTask, double timeout) \r
 222                                 throw(NativeException);\r
 223                                 \r
 224                                 void send(const char* alias, const Task& rTask, double timeout) \r
 225                                 throw(NativeException);\r
 226                                 \r
 227                                 void sendBounded(const Task& rTask, double maxRate) \r
 228                                 throw(NativeException);\r
 229                                 \r
 230                                 void sendBounded(const char* alias, const Task& rTask, double maxRate) \r
 231                                 throw(NativeException);\r
 232                                 \r
 233                          \r
 234                         \r
 235                         \r
 236                         protected:\r
 237                         // Attributes.\r
 238                         \r
 239                                 /**\r
 240                                  * This attribute represents the msg native host object. \r
 241                                  * It is set automaticatly during the call of the static \r
 242                                  * method Host::getByName().\r
 243                                  *\r
 244                                  * @see                         Host::getByName().\r
 245                                  */ \r
 246                                 m_host_t nativeHost;\r
 247                         \r
 248                         private:\r
 249                                 /**\r
 250                                  * User host data. \r
 251                                  */ \r
 252                                 void* data;\r
 253                 };\r
 254                 \r
 255                 typedef Host* HostPtr;\r
 256         } // namespace Msg\r
 257 } // namespace SimGrid\r
 258 \r
 259 #endif // !MSG_HOST_HPP