src/cxx/Task.hpp

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