src/cxx/Task.hpp

   1 /*\r
   2  * Task.hpp\r
   3  *\r
   4  * This file contains the declaration of the wrapper class of the native MSG task type.\r
   5  *\r
   6  * Copyright 2006,2007 Martin Quinson, Malek Cherier           \r
   7  * All right reserved. \r
   8  *\r
   9  * This program is free software; you can redistribute \r
  10  * it and/or modify it under the terms of the license \r
  11  *(GNU LGPL) which comes with this package. \r
  12  *\r
  13  */  \r
  14  \r
  15 #ifndef MSG_TASK_HPP\r
  16 #define MSG_TASK_HPP\r
  17 \r
  18 // Compilation C++ recquise\r
  19 #ifndef __cplusplus\r
  20         #error Process.hpp requires C++ compilation (use a .cxx suffix)\r
  21 #endif\r
  22 \r
  23 namespace SimGrid\r
  24 {\r
  25         namespace Msg\r
  26         {\r
  27                 // SimGrid::Msg::Task wrapper class declaration.\r
  28                 class Task\r
  29                 {\r
  30                         protected:\r
  31                                 // Default constructor.\r
  32                                 Task();\r
  33                                 \r
  34                         public:\r
  35                                 /*! \brief Copy constructor.\r
  36                                  */\r
  37                                 Task(const Task& rTask);\r
  38                                 \r
  39                                 /*! \brief Destructor.\r
  40                                  *\r
  41                                  * \exception                           If the destructor failed, it throw the exception described below:\r
  42                                  *\r
  43                                  *                                                      [MsgException]                          if a native exception occurs.\r
  44                                  */\r
  45                                 virtual ~Task()\r
  46                                 throw(MsgException);\r
  47                                 \r
  48                                 /*! \brief Constructs an new task with the specified processing amount and amount\r
  49                                  * of data needed.\r
  50                                  *\r
  51                                  * \param name                          Task's name\r
  52                                  * \param computeDuration       A value of the processing amount (in flop) needed to process the task. \r
  53                                  *                                                      If 0, then it cannot be executed with the execute() method.\r
  54                                  *                                                      This value has to be >= 0.\r
  55                                  * \param messageSize           A value of amount of data (in bytes) needed to transfert this task.\r
  56                                  *                                                      If 0, then it cannot be transfered with the get() and put() methods.\r
  57                                  *                                                      This value has to be >= 0.\r
  58                                  *\r
  59                                  * \exception                           If this method failed, it throws one of the exceptions described below:\r
  60                                  *\r
  61                                  *                                                      [InvalidArgumentException]      if the parameter computeDuration or messageSize\r
  62                                  *                                                                                                              is negative.\r
  63                                  *                                                      [NullPointerException]          if the parameter name is NULL.\r
  64                                  *\r
  65                                  *                                                      [MsgException]                          if a internal exception occurs.\r
  66                                  */\r
  67                                 Task(const char* name, double computeDuration, double messageSize)\r
  68                                 throw (InvalidArgumentException, NullPointerException);\r
  69                                 \r
  70                                 /*! \Constructs an new parallel task with the specified processing amount and amount for each host\r
  71                              * implied.\r
  72                              *\r
  73                              * \param name                              The name of the parallel task.\r
  74                              * \param hosts                             The list of hosts implied by the parallel task.\r
  75                              * \param computeDurations  The amount of operations to be performed by each host of \a hosts.\r
  76                              * \param messageSizes              A matrix describing the amount of data to exchange between hosts.\r
  77                              * \hostCount                               The number of hosts implied in the parallel task.\r
  78                              * \r
  79                              * \exception                               If this method fails, it throws one of the exceptions described below:\r
  80                              *\r
  81                              *                                                  [NullPointerException]          if the parameter name is NULL or\r
  82                              *                                                                                                          if the parameter computeDurations is NULL or\r
  83                              *                                                                                                          if the parameter messageSizes is NULL\r
  84                              *\r
  85                              *                                                  [InvalidArgumentException]      if the parameter hostCount is negative or zero.                                                 \r
  86                              */\r
  87                                 Task(const char* name, Host* hosts, double* computeDurations, double* messageSizes, int hostCount)\r
  88                                 throw(NullPointerException, InvalidArgumentException);\r
  89                         \r
  90                         \r
  91                                 /*! \brief Task::getName() - Gets the names of the task.\r
  92                                  *\r
  93                                  * \return                                      The name of the task.\r
  94                                  */\r
  95                                 const char* getName(void) const;\r
  96                         \r
  97                                 /*! \brief Task::getSender() - Gets the sender of the task.\r
  98                                  *\r
  99                                  * \return                                      A reference to the sender of the task.\r
 100                                  */\r
 101                                 Process& getSender(void) const;\r
 102                                 \r
 103                                 /*! \brief Task::getSource() - Gets the source of the task.\r
 104                                  * \r
 105                                  * \return                                      A reference to the source of the task.\r
 106                                  */\r
 107                                 Host& getSource(void) const;\r
 108                                 \r
 109                                 /*! \brief Task::getComputeDuration() - Get the computing amount of the task.\r
 110                                  *\r
 111                                  * \return                                      The computing amount of the task.\r
 112                                  */\r
 113                         \r
 114                                 double getComputeDuration(void) const;\r
 115                                 \r
 116                                 /*! \brief Task::getRemainingDuration() - Gets the remaining computation.\r
 117                                  *\r
 118                                  * \return                                      The remining computation of the task.\r
 119                                  */\r
 120                                 double getRemainingDuration(void) const;\r
 121                         \r
 122                                 /*! \brief Task::setPrirority() -  Sets the priority of the computation of the task.\r
 123                          * The priority doesn't affect the transfert rate. For example a\r
 124                          * priority of 2 will make the task receive two times more cpu than\r
 125                          * the other ones.\r
 126                          *\r
 127                          * \param priority                      The new priority of the task.\r
 128                          *\r
 129                          * execption                            If this method fails, it throws the exception described below:\r
 130                          *\r
 131                          *                                                      [InvalidArgumentException]      if the parameter priority is negative.\r
 132                          */\r
 133                                 void setPriority(double priority)\r
 134                                 throw(InvalidArgumentException);\r
 135                                 \r
 136                                 /*! \brief Task::get() - Gets a task from the specified channel of the host of the current process.\r
 137                                  *\r
 138                                  * \param channel                       The channel number to get the task.\r
 139                                  *\r
 140                                  * \return                                      If successful the method returns the task. Otherwise the method throws one\r
 141                                  *                                                      of the exceptions described below:\r
 142                                  *\r
 143                                  * \exception                           [InvalidArgumentException]      if the channel parameter is negative.\r
 144                                  *                                      \r
 145                                  *                                                      [MsgException]                          if an internal excpetion occurs.\r
 146                                  */\r
 147                                 static Task& get(int channel) \r
 148                                 throw(InvalidArgumentException, MsgException); \r
 149                                 \r
 150                                 /*! \brief      Task::get() - Gets a task from the given channel number of the given host.      \r
 151                                  *\r
 152                                  * \param channel                       The channel number.\r
 153                                  * \param rHost                         A reference of the host owning the channel.\r
 154                                  *\r
 155                                  * \return                                      If successful, the method returns the task. Otherwise the method\r
 156                                  *                                                      throw one of the exceptions described below:\r
 157                                  *\r
 158                                  * \exception                           [InvalidArgumentException]      if the channel number is negative.\r
 159                                  *\r
 160                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 161                                  */\r
 162                                 static Task& get(int channel, const Host& rHost) \r
 163                                 throw(InvalidArgumentException, MsgException);\r
 164                                 \r
 165                                 /*! \brief Task::get() - Gets a task from the specified channel of the specified host\r
 166                                  *  (waiting at most given time).\r
 167                                  *\r
 168                                  * \param channel                       The channel number.\r
 169                                  * \param timeout                       The timeout value.\r
 170                                  * \param rHost                         A reference to the host owning the channel.\r
 171                                  *\r
 172                                  * \return                                      If successful, the method returns the task. Otherwise the method returns\r
 173                                  *                                                      one of the exceptions described below:\r
 174                                  *\r
 175                                  * \exception                           [InvalidArgumentException]      if the channel number is negative or\r
 176                                  *                                                                                                              if the timeout value is negative and \r
 177                                  *                                                                                                              different than -1.0.\r
 178                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 179                                  */\r
 180                                 static Task& get(int channel, double timeout, const Host& rHost) \r
 181                                 throw(InvalidArgumentException, MsgException);  \r
 182                                 \r
 183                                 /*! \brief Task::probe() - Probes whether there is a waiting task on the given channel of local host.\r
 184                                  *\r
 185                                  * \param channel                       The channel number.\r
 186                                  *\r
 187                                  * \return                                      If there is a waiting task on the channel the method returns true. Otherwise\r
 188                                  *                                                      the method returns false.\r
 189                                  *\r
 190                                  * \exception                           If this method fails, it throws the exception described below:\r
 191                                  *\r
 192                                  *                                                      [InvalidArgumentException]      if the parameter channel is negative.\r
 193                                  */\r
 194                                 static bool probe(int channel)\r
 195                                 throw(InvalidArgumentException);\r
 196                                 \r
 197                                 /*! \brief Task::probe() - Counts tasks waiting on the given channel of local host and sent by given host.\r
 198                                  *\r
 199                                  * \param channel                       The channel id.\r
 200                                  * \param rHost                         A reference to the host that has sent the task.\r
 201                                  *\r
 202                                  * \return                                      The number of tasks.\r
 203                                  *\r
 204                                  * \exception                           [InvalidArgumentException]      if the parameter channel is negative.\r
 205                                  */\r
 206                                 static int probe(int channel, const Host& rHost)\r
 207                                 throw(InvalidArgumentException);\r
 208                                 \r
 209                                 /*! \brief Task::execute() - This method executes a task on the location on which the\r
 210                                  * process is running.\r
 211                                  *\r
 212                                  * \exception                           If this method fails, it returns the exception described below:\r
 213                                  *\r
 214                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 215                                  */\r
 216                                 void execute(void) \r
 217                                 throw(MsgException);\r
 218                                 \r
 219                                 /*! \brief Task::cancel() - This method cancels a task.\r
 220                                  *\r
 221                                  * \exception                           If this method fails, it returns the exception described below:\r
 222                                  *\r
 223                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 224                                  */\r
 225                                 void cancel(void) \r
 226                                 throw(MsgException);\r
 227                         \r
 228                                 /*! \brief Task::send() - Send the task on the mailbox identified by the default alias.\r
 229                                  *\r
 230                                  * \exception                           If this method failed, it returns one of the exceptions described\r
 231                                  *                                                      below:\r
 232                                  *\r
 233                                  *                                                      [BadAllocException]                     if there is not enough memory to build the default alias.\r
 234                                  *\r
 235                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 236                                  */\r
 237                                 void send(void) \r
 238                                 throw(BadAllocException, MsgException);\r
 239                                 \r
 240                                 /*! \brief Task::send() - Send the task on the mailbox identified by the given alias.\r
 241                                  *\r
 242                                  * \param alias                         The alias of the mailbox where to send the task.\r
 243                                  *\r
 244                                  * \exception                           If this method failed, it returns one of the exceptions described\r
 245                                  *                                                      below:\r
 246                                  *\r
 247                                  *                                                      [NullPointerException]          if there parameter alias is NULL.\r
 248                                  *\r
 249                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 250                                  */ \r
 251                                 void send(const char* alias) \r
 252                                 throw(NullPointerException, MsgException);\r
 253                                 \r
 254                                 /*! \brief Task::send() - Send the task on the mailbox identified by the default alias\r
 255                                  * (waiting at most given time).\r
 256                                  *\r
 257                                  * \param timeout                       The timeout value.\r
 258                                  *\r
 259                                  * \exception                           If this method failed, it returns one of the exceptions described\r
 260                                  *                                                      below:\r
 261                                  *\r
 262                                  *                                                      [BadAllocException]                     if there is not enough memory to build the default alias.\r
 263                                  *\r
 264                                  *                                                      [InvalidArgumentException]      if the timeout value is negative or different -1.0.\r
 265                                  *\r
 266                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 267                                  */\r
 268                                 void send(double timeout) \r
 269                                 throw(BadAllocationException, InvalidArgumentException, MsgException);\r
 270                                 \r
 271                                 /*! \brief Task::send() - Send the task on the mailbox identified by a given alias\r
 272                                  * (waiting at most given time).\r
 273                                  *\r
 274                                  * \param alias                         The alias of the mailbox where to send the task.\r
 275                                  * \param timeout                       The timeout value.\r
 276                                  *\r
 277                                  * \exception                           If this method failed, it returns one of the exceptions described\r
 278                                  *                                                      below:\r
 279                                  *\r
 280                                  *                                                      [NullPointerException]          if alias parameter is NULL.\r
 281                                  *\r
 282                                  *                                                      [InvalidArgumentException]      if the timeout value is negative or different -1.0.\r
 283                                  *\r
 284                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 285                                  */\r
 286                                 void send(const char* alias, double timeout) \r
 287                                 throw(NullPointerException, InvalidArgumentException, MsgException);\r
 288                                 \r
 289                                 /*! \brief Task::sendBounded() - Sends the task on the mailbox identified by the default alias.\r
 290                                  * (capping the emision rate to maxrate).\r
 291                                  *\r
 292                                  * \param maxRate                       The maximum rate value.\r
 293                                  *\r
 294                                  * \exception                           If this method failed, it throws one of the exceptions described below:\r
 295                                  *\r
 296                                  *                                                      [BadAllocException]                     if there is not enough memory to build the default alias.\r
 297                                  *\r
 298                                  *                                                      [InvalidArgumentException]      if the parameter maxRate is negative and different\r
 299                                  *                                                                                                              than -1.0.\r
 300                                  *\r
 301                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 302                                  */\r
 303                                 void sendBounded(double maxRate) \r
 304                                 throw(BadAllocException, InvalidArgumentException, MsgException);\r
 305                                 \r
 306                                 /*! \brief Task::sendBounded() - Sends the task on the mailbox identified by the given alias.\r
 307                                  * (capping the emision rate to maxrate).\r
 308                                  *\r
 309                                  *\ param alias                         The alias of the mailbox where to send the task.\r
 310                                  * \param maxRate                       The maximum rate value.\r
 311                                  *\r
 312                                  * \exception                           If this method failed, it throws one of the exceptions described below:\r
 313                                  *\r
 314                                  *                                                      [NullPointerException]          if the alias parameter is NULL.\r
 315                                  *\r
 316                                  *                                                      [InvalidArgumentException]      if the parameter maxRate is negative and different\r
 317                                  *                                                                                                              than -1.0.\r
 318                                  *\r
 319                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 320                                  */\r
 321                                 void sendBounded(const char* alias, double maxRate) \r
 322                                 throw(NullPointerException, InvalidArgumentException, MsgException);\r
 323                                 \r
 324                                 \r
 325                                 /*! \brief Task::receive() - Receives a task from the mailbox identified by the default alias (located\r
 326                                  * on the local host).\r
 327                                  *\r
 328                                  * \return                                      A reference to the task.\r
 329                                  *\r
 330                                  * \exception                           If this method failed, it throws one of the exception described below:\r
 331                                  *\r
 332                                  *                                                      [BadAllocException]                     if there is not enough memory to build the default alias.\r
 333                                  *\r
 334                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 335                                  */\r
 336                                 static Task& receive(void) \r
 337                                 throw(BadAllocException, MsgException);\r
 338                                 \r
 339                                 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias (located\r
 340                                  * on the local host).\r
 341                                  *\r
 342                                  * \alias                                       The alias of the mailbox.\r
 343                                  *\r
 344                                  * \return                                      A reference to the task.\r
 345                                  *\r
 346                                  * \exception                           If this method failed, it throws one of the exception described below:\r
 347                                  *\r
 348                                  *                                                      [NullPointerException]          if the alias parameter is NULL.\r
 349                                  *\r
 350                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 351                                  */\r
 352                                 static Task& receive(const char* alias) \r
 353                                 throw(NullPointerException, MsgException);\r
 354                                 \r
 355                                 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias (located\r
 356                                  * on the local host and waiting at most given time).\r
 357                                  *\r
 358                                  * \alias                                       The alias of the mailbox.\r
 359                                  * \timeout                                     The timeout value.\r
 360                                  *\r
 361                                  * \return                                      A reference to the task.\r
 362                                  *\r
 363                                  * \exception                           If this method failed, it throws one of the exception described below:\r
 364                                  *\r
 365                                  *                                                      [NullPointerException]          if the alias parameter is NULL.\r
 366                                  *\r
 367                                  *                                                      [InvalidArgumentException]      if the timeout value is negatif and different than\r
 368                                  *                                                                                                              -1.0.\r
 369                                  *\r
 370                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 371                                  */\r
 372                                 static Task& receive(const char* alias, double timeout) \r
 373                                 throw(NullPointerException, InvalidArgumentException, MsgException);\r
 374                                 \r
 375                                 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias located\r
 376                                  * on the given host.\r
 377                                  *\r
 378                                  * \alias                                       The alias of the mailbox.\r
 379                                  * \rHost                                       The location of the mailbox.\r
 380                                  *\r
 381                                  * \return                                      A reference to the task.\r
 382                                  *\r
 383                                  * \exception                           If this method failed, it throws one of the exception described below:\r
 384                                  *\r
 385                                  *                                                      [NullPointerException]          if the alias parameter is NULL.\r
 386                                  *\r
 387                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 388                                  */\r
 389                                 static Task& receive(const char* alias, const Host& rHost) \r
 390                                 throw(NullPointerException, MsgException);\r
 391                                 \r
 392                                 /*! \brief Task::receive() - Receives a task from the mailbox identified by a given alias located\r
 393                                  * on the given host (and waiting at most given time).\r
 394                                  *\r
 395                                  * \alias                                       The alias of the mailbox.\r
 396                                  * \timeout                                     The timeout value.\r
 397                                  * \rHost                                       The location of the mailbox.\r
 398                                  *\r
 399                                  * \return                                      A reference to the task.\r
 400                                  *\r
 401                                  * \exception                           If this method failed, it throws one of the exception described below:\r
 402                                  *\r
 403                                  *                                                      [NullPointerException]          if the alias parameter is NULL.\r
 404                                  *\r
 405                                  *                                                      [InvalidArgumentException]      if the timeout value is negatif and different than\r
 406                                  *                                                                                                              -1.0.\r
 407                                  *\r
 408                                  *                                                      [MsgException]                          if an internal exception occurs.\r
 409                                  */\r
 410                                 static Task& receive(const char* alias, double timeout, const Host& rHost) \r
 411                                 throw(NullPointerException, InvalidArgumentException, MsgException);\r
 412                                 \r
 413                                 /*! \brief Task::listen() - Listen whether there is a waiting task on the mailbox \r
 414                                  * identified by the default alias of local host.\r
 415                                  *\r
 416                                  * \return                                      If there is a waiting task on the mailbox the method returns true.\r
 417                                  *                                                      Otherwise the method returns false.\r
 418                                  *\r
 419                                  * \exception                           If this method fails, it throws one of the exceptions described below:\r
 420                                  *\r
 421                                  *                                                      [BadAllocException]                     if there is not enough memory to build the default alias.\r
 422                                  */\r
 423                                 static bool listen(void) \r
 424                                 throw(BadAllocException);\r
 425                                 \r
 426                                 /*! \brief Task::listen() - Listen whether there is a waiting task on the mailbox \r
 427                                  * identified by the given alias of local host.\r
 428                                  *\r
 429                                  * \param alias                         The alias of the mailbox.\r
 430                                  *\r
 431                                  * \return                                      If there is a waiting task on the mailbox the method returns true.\r
 432                                  *                                                      Otherwise the method returns false.\r
 433                                  *\r
 434                                  * \exception                           If this method fails, it throws one of the exceptions described below:\r
 435                                  *\r
 436                                  *                                                      [NullPointerException]          if the parameter alias is NULL.\r
 437                                  */\r
 438                                 static bool listen(const char* alias) \r
 439                                 throw(NullPointerException);\r
 440                                 \r
 441                                 /*! \brief Task::listenFrom() - Tests whether there is a pending communication on the mailbox \r
 442                                  * identified by the default alias, and who sent it.\r
 443                                  *\r
 444                                  * \return                                      If there is a pending communication on the mailbox, the method returns\r
 445                                  *                                                      the PID of it sender. Otherwise the method returns -1.\r
 446                                  *\r
 447                                  * \exception                           If this method fails, it throws the exception described below:\r
 448                                  *\r
 449                                  *                                                      [BadAllocException]                     if there is not enough memory to build the default\r
 450                                  *                                                                                                              alias.\r
 451                                  */\r
 452                                 static int listenFrom(void) \r
 453                                 throw(BadAllocException);\r
 454                                 \r
 455                                 /*! \brief Task::listenFrom() - Tests whether there is a pending communication on the mailbox \r
 456                                  * identified by the specified alias, and who sent it.\r
 457                                  *\r
 458                                  * \alias                                       The alias of the mailbox.\r
 459                                  *\r
 460                                  * \return                                      If there is a pending communication on the mailbox, the method returns\r
 461                                  *                                                      the PID of it sender. Otherwise the method returns -1.\r
 462                                  *\r
 463                                  * \exception                           If this method fails, it throws the exception described below:\r
 464                                  *\r
 465                                  *                                                      [NullPointerException]          if the alias parameter is NULL.\r
 466                                  */\r
 467                                 static int listenFrom(const char* alias) \r
 468                                 throw(NullPointerException);\r
 469                                 \r
 470                                 /*! \brief Task::listenFromHost() - Tests whether there is a pending communication on the mailbox \r
 471                                  * identified by the default alias and located on the host of the current process, and who sent it.\r
 472                                  *\r
 473                                  * \param rHost                         The location of the mailbox.\r
 474                                  *\r
 475                                  * \return                                      If there is a pending communication on the mailbox, the method returns\r
 476                                  *                                                      the PID of it sender. Otherwise the method returns -1.\r
 477                                  *\r
 478                                  * \exception                           If this method fails, it throws the exception described below:\r
 479                                  *\r
 480                                  *                                                      [BadAllocException]                     if there is not enough memory to build the default\r
 481                                  *                                                                                                              alias.\r
 482                                  */\r
 483                                 static int listenFromHost(const Host& rHost) \r
 484                                 throw(BadAllocException);\r
 485                                 \r
 486                                 /*! \brief Task::listenFromHost() - Tests whether there is a pending communication on the mailbox \r
 487                                  * identified by the default alias and located on the host of the current process, and who sent it.\r
 488                                  *\r
 489                                  * \param rHost                         The location of the mailbox.\r
 490                                  *\r
 491                                  * \return                                      If there is a pending communication on the mailbox, the method returns\r
 492                                  *                                                      the PID of it sender. Otherwise the method returns -1.\r
 493                                  *\r
 494                                  * \exception                           If this method fails, it throws the exception described below:\r
 495                                  *\r
 496                                  *                                                      [BadAllocException]                     if there is not enough memory to build the default\r
 497                                  *                                                                                                              alias.\r
 498                                  */\r
 499                                 static bool listenFromHost(const char* alias, const Host& rHost) \r
 500                                 throw(NullPointerException, NativeException);\r
 501                         \r
 502                         private:\r
 503                                 \r
 504                                 // Attributes.\r
 505                                 \r
 506                                         m_task_t nativeTask;    // the native MSG task.\r
 507                 };\r
 508         \r
 509         } // namespace Msg \r
 510 } // namespace SimGrid\r
 511 \r
 512 #endif // §MSG_TASK_HPP