src/cxx/MsgHost.hpp

   1 /*
   2  * Host.hpp
   3  *
   4  * Copyright 2006,2007 Martin Quinson, Malek Cherier
   5  * All right reserved.
   6  *
   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.
  10  *
  11  */
  12 #ifndef MSG_HOST_HPP
  13 #define MSG_HOST_HPP
  14
  15
  16 /*! \brief Host class declaration.
  17  *
  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.
  26  *
  27  * The best way to get an host is to call the static method
  28  * Host.getByName() which returns a reference.
  29  *
  30  * For example to get the instance of the host. If your platform
  31  * file description contains an host named "Jacquelin" :
  32  *
  33  * \verbatim
  34 using namespace SimGrid.Msg;
  35
  36 Host jacquelin;
  37
  38 try
  39 {
  40         jacquelin = Host::getByName("Jacquelin");
  41 }
  42 catch(HostNotFoundException e)
  43 {
  44         cerr << e.toString();
  45 }
  46 ...
  47 \endverbatim
  48  *
  49  */
  50
  51 #ifndef __cplusplus
  52         #error Host.hpp requires C++ compilation (use a .cxx suffix)
  53 #endif
  54
  55 #include <msg/datatypes.h>
  56
  57 #include <InvalidArgumentException.hpp>
  58 #include <BadAllocException.hpp>
  59 #include <HostNotFoundException.hpp>
  60 #include <MsgException.hpp>
  61 #include <NullPointerException.hpp>
  62
  63
  64
  65 // namespace SimGrid::Msg
  66 namespace SimGrid
  67 {
  68         namespace Msg
  69         {
  70                 class Task;
  71                 class Process;
  72
  73                 // Declaration of the class SimGrid::Msg::Host.
  74                 class SIMGRIDX_EXPORT Host // final class.
  75                 {
  76                         friend class Process;
  77                         friend class Task;
  78
  79                         // Desable the default constructor.
  80                         // The best way to get an host instance is to use the static method Host::getByName().
  81
  82                         public :
  83
  84                         // Default constructor (desabled).
  85                                 Host();
  86
  87                         public:
  88
  89                         // Copy constructor (desabled).
  90                                 Host(const Host& rHost);
  91
  92                         // Destructor (desable).
  93                                 virtual ~Host();
  94
  95                         // Operations
  96
  97                                 /*! \brief Host::getByName() - returns an host by its name
  98                                  *
  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.
 101                                  *
 102                                  * \param hostName      The name of the host.
 103                                  *
 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.
 108                                  *
 109                                  * \exception           [HostNotFoundException]         if no host with the specified name
 110                                  *                                                                                              was found.
 111                                  *                                      [InvalidArgumentException]      if the hostName parameter is invalid (NULL).
 112                                  *                                      [BadAllocException]                     if there is not enough memory to allocate the host.
 113                                  */
 114                                 static Host& getByName(const char* hostName)
 115                                 throw(HostNotFoundException, NullPointerException, BadAllocException);
 116
 117                                 /*! \brief Host::getNumber() - returns the number of the installed hosts.
 118                                  *
 119                                  * \return                      The number of hosts installed.
 120                                  */
 121                                 static int getNumber(void);
 122
 123
 124                                 /*! \brief Host::currentHost() - This static method returns the location on which the current
 125                                  * process is executed.
 126                                  *
 127                                  * \return                      The host of the current process.
 128                                  *
 129                                  * \see                         Process::currentProcess().
 130                                  */
 131                                 static Host& currentHost(void);
 132
 133                                 /*! \brief Host::all() - This static method retrieves all of the hosts of the installed platform.
 134                                  *
 135                                  * \param hosts         A pointer to array of Host pointers that receives all the hosts of the platform.
 136                                  *
 137                                  * \param len           A pointer to the length of the table of pointers.
 138                                  *
 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.
 142                                  *
 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.
 149                                  *
 150                                  *
 151                                  * \remark                      To get the number of hosts installed on your platform use the static method
 152                                  *                                      Host::getNumber().
 153                                  *
 154                                  * \see                         Host::getNumber().
 155                                  *
 156                                  *\verbatim
 157                                  * // This example show how to use this method to get the list of hosts installed on your platform.
 158                                  *
 159                                  *      using namespace SimGrid::Msg;
 160                                  *      using <iostream>
 161                                  *
 162                                  *      // (1) get the number of hosts.
 163                                  *      int number = Host::getNumber();
 164                                  *
 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.
 168                                  *
 169                                  *      // (3) call the method
 170                                  *      try
 171                                  *      {
 172                                  *              Host::all(&ar, &number);
 173                                  *      }
 174                                  *      catch(BadAllocException e)
 175                                  *      {
 176                                  *              cerr << e.toString() << endl;
 177                                  *              ...
 178                                  *      }
 179                                  *      catch(InvalidArgumentException e)
 180                                  *      {
 181                                  *              cerr << e.toString() << endl;
 182                                  *              ..
 183                                  *      }
 184                                  *
 185                                  *      // (4) use the table of host (for example print all the name of all the hosts);
 186                                  *
 187                                  *      for(int i = 0; i < number ; i++)
 188                                  *              cout << ar[i]->getName() << endl;
 189                                  *
 190                                  *      ...
 191                                  *
 192                                  *      // (5) release the allocate table
 193                                  *
 194                                  *      delete[] ar;
 195                                  *
 196                                  */
 197                                 static void all(Host*** hosts /*in|out*/, int* len /*in|out*/)
 198                                 throw(InvalidArgumentException, BadAllocException) ;
 199
 200                                 /*! \brief Host::getName() - This method return the name of the Msg host object.
 201                                  *
 202                                  * \return                      The name of the host object.
 203                                  */
 204                                 const char* getName(void) const;
 205
 206                                 /*! \brief Host::setData() - Set the user data of an host object.
 207                                  *
 208                                  * \param data          The user data to set.
 209                                  */
 210                                 void setData(void* data);
 211
 212                                 /*! \brief Host::getData() - Get the user data of a host object.
 213                                  *
 214                                  * \return                      The user data of the host object.
 215                                  */
 216                                 void* getData(void) const;
 217
 218                                 /*! \brief Host::hasData() - Test if an host object has some data.
 219                                  *
 220                                  * \return                      This method returns true if the host object has some user data.
 221                                  *                                      Otherwise the method returns false.
 222                                  */
 223                                 bool hasData(void) const;
 224
 225                                 /*! \brief Host::getRunningTaskNumber() - returns the number of tasks currently running on a host.
 226                                  *
 227                                  * \return                      The number of task currently running of the host object.
 228                                  *
 229                                  * \remark                      The external load is not taken in account.
 230                                  */
 231                                 int getRunningTaskNumber(void) const;
 232
 233                                 /*! \brief Host::getSpeed() - returns the speed of the processor of a host,
 234                                  * regardless of the current load of the machine.
 235                                  *
 236                                  * \return                      The speed of the processor of the host in flops.
 237                                  */
 238                                 double getSpeed(void) const;
 239
 240                                 /*! \brief Host::isAvailable - tests if an host is availabled.
 241                                  *
 242                                  * \return                      Is the host is availabled the method returns
 243                                  *                                      1. Otherwise the method returns 0.
 244                                  */
 245                                 int isAvailable(void) const;
 246
 247                                 /* ! \brief Host::put() - put a task on the given channel of a host .
 248                                  *
 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.
 252                                  *
 253                                  * \return                      If successful the task is puted on the specified channel. Otherwise
 254                                  *                                      the method throws one of the exceptions described below.
 255                                  *
 256                                  * \exception           [MsgException]                          if an internal error occurs.
 257                                  *                                      [InvalidArgumentException]      if the value of the channel specified as
 258                                  *                                                                                              parameter is negative.
 259                                  */
 260                                 void put(int channel, Task* task)
 261                                 throw(MsgException, InvalidArgumentException);
 262
 263                                 /* ! \brief Host::put() - put a task on the given channel of a host object (waiting at most timeout seconds).
 264                                  *
 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.
 269                                  *
 270                                  * \return                      If successful the task is puted on the specified channel. Otherwise
 271                                  *                                      the method throws one of the exceptions described below.
 272                                  *
 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.
 277                                  *
 278                                  * \remark                      To specify no timeout set the timeout value with -1.0.
 279                                  */
 280                                 void put(int channel, Task* task, double timeout)
 281                                 throw(MsgException, InvalidArgumentException);
 282
 283                                 /* ! \brief Host::putBounded() - put a task on the given channel of a host object (capping the emission rate to maxrate).
 284                                  *
 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.
 289                                  *
 290                                  * \return                      If successful the task is puted on the specified channel. Otherwise
 291                                  *                                      the method throws one of the exceptions described below.
 292                                  *
 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.
 297                                  *
 298                                  * \remark                      To specify no rate set the maxRate parameter value with -1.0.
 299                                  */
 300                                 void putBounded(int channel, Task* task, double maxRate)
 301                                 throw(MsgException, InvalidArgumentException);
 302
 303                                 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias.
 304                                  *
 305                                  * \param rTask         A reference to the task object containing the native msg task to send.
 306                                  *
 307                                  * \return                      If successful the task is sended to the default mailbox. Otherwise the
 308                                  *                                      method throws one of the exceptions described below.
 309                                  *
 310                                  * \exception           [BadAllocException]                     if there is not enough memory to allocate
 311                                  *                                                                                              the default alias variable.
 312                                  *                                      [MsgException]                          if an internal error occurs.
 313                                  */
 314                                 void send(Task* task)
 315                                 throw(MsgException, BadAllocException);
 316
 317                                 /* ! brief Host::send() - sends the given task to mailbox identified by the specified alias parameter.
 318                                  *
 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.
 321                                  *
 322                                  * \return                      If successful the task is sended to the default mailbox. Otherwise the
 323                                  *                                      method throws one of the exceptions described below.
 324                                  *
 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.
 329                                  */
 330                                 void send(const char* alias, Task* task)
 331                                 throw(InvalidArgumentException, MsgException);
 332
 333                                 /* ! brief Host::send() - sends the given task to mailbox identified by the default alias
 334                                  *  (waiting at most timeout seconds).
 335                                  *
 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.
 338                                  *
 339                                  * \return                      If successful the task is sended to the default mailbox. Otherwise the
 340                                  *                                      method throws one of the exceptions described below.
 341                                  *
 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
 345                                  *                                                                                              -1.0.
 346                                  *                                      [MsgException]                          if an internal error occurs.
 347                                  *
 348                                  * \remark                      To specify no timeout set the timeout value with -1.0 or use the previous
 349                                  *                                      version of this method.
 350                                  *
 351                                  */
 352                                 void send(Task* task, double timeout)
 353                                 throw(InvalidArgumentException, BadAllocException, MsgException);
 354
 355                                 /* ! brief Host::send() - sends the given task to mailbox identified by the parameter alias
 356                                  *  (waiting at most timeout seconds).
 357                                  *
 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.
 361                                  *
 362                                  * \return                      If successful the task is sended to the default mailbox. Otherwise the
 363                                  *                                      method throws one of the exceptions described below.
 364                                  *
 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.
 368                                  *
 369                                  * \remark                      To specify no timeout set the timeout value with -1.0 or use the previous
 370                                  *                                      version of this method.
 371                                  *
 372                                  */
 373                                 void send(const char* alias, Task* task, double timeout)
 374                                 throw(InvalidArgumentException, MsgException);
 375
 376                                 /* ! brief Host::sendBounded() - sends the given task to mailbox associated to the default alias
 377                                  *  (capping the emission rate to maxRate).
 378                                  *
 379                                  * \param rTask         A reference to the task object containing the native msg task to send.
 380                                  * \param maxRate       The maximum rate value.
 381                                  *
 382                                  * \return                      If successful the task is sended to the default mailbox. Otherwise the
 383                                  *                                      method throws one of the exceptions described below.
 384                                  *
 385                                  * \exception           [InvalidArgumentException]      if the maximum rate value is negative and different of
 386                                  *                                                                                              -1.0.
 387                                  *                                      [MsgException]                          if an internal error occurs.
 388                                  *                                      [BadAllocException]                     if there is not enough memory to allocate
 389                                  *                                                                                              the default alias variable.
 390                                  *
 391                                  * \remark                      To specify no rate set its value with -1.0.
 392                                  *
 393                                  */
 394                                 void sendBounded(Task* task, double maxRate)
 395                                 throw(InvalidArgumentException, BadAllocException, MsgException);
 396
 397                                 /* ! brief Host::sendBounded() - sends the given task to mailbox identified by the parameter alias
 398                                  *  (capping the emission rate to maxRate).
 399                                  *
 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.
 403                                  *
 404                                  * \return                      If successful the task is sended to the default mailbox. Otherwise the
 405                                  *                                      method throws one of the exceptions described below.
 406                                  *
 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.
 410                                  *
 411                                  * \remark                      To specify no rate set its value with -1.0.
 412                                  *
 413                                  */
 414                                 void sendBounded(const char* alias, Task* task, double maxRate)
 415                                 throw(InvalidArgumentException, MsgException);
 416
 417                         protected:
 418                         // Attributes.
 419
 420                                 /**
 421                                  * This attribute represents the msg native host object.
 422                                  * It is set automaticatly during the call of the static
 423                                  * method Host::getByName().
 424                                  *
 425                                  * \see                         Host::getByName().
 426                                  */
 427                                 m_host_t nativeHost;
 428
 429                         private:
 430                                 /**
 431                                  * User host data.
 432                                  */
 433                                 void* data;
 434                 };
 435
 436                 typedef Host* HostPtr;
 437         } // namespace Msg
 438 } // namespace SimGrid
 439
 440 #endif // !MSG_HOST_HPP