src/msg/gos.c

   1 /* Copyright (c) 2004, 2005, 2006, 2007, 2008, 2009, 2010. The SimGrid Team.
   2  * All rights reserved.                                                     */
   3
   4 /* This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the license (GNU LGPL) which comes with this package. */
   6
   7 #include "private.h"
   8 #include "xbt/sysdep.h"
   9 #include "mc/mc.h"
  10 #include "xbt/log.h"
  11 #include "mailbox.h"
  12
  13
  14 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_gos, msg,
  15                                 "Logging specific to MSG (gos)");
  16
  17 /** \ingroup msg_gos_functions
  18  *
  19  * \brief Return the last value returned by a MSG function (except
  20  * MSG_get_errno...).
  21  */
  22 MSG_error_t MSG_get_errno(void)
  23 {
  24   return PROCESS_GET_ERRNO();
  25 }
  26
  27 /** \ingroup msg_gos_functions
  28  * \brief Executes a task and waits for its termination.
  29  *
  30  * This function is used for describing the behavior of an agent. It
  31  * takes only one parameter.
  32  * \param task a #m_task_t to execute on the location on which the
  33  agent is running.
  34  * \return #MSG_FATAL if \a task is not properly initialized and
  35  * #MSG_OK otherwise.
  36  */
  37 MSG_error_t MSG_task_execute(m_task_t task)
  38 {
  39   simdata_task_t simdata = NULL;
  40   m_process_t self = MSG_process_self();
  41   e_smx_state_t comp_state;
  42   CHECK_HOST();
  43
  44   simdata = task->simdata;
  45
  46   xbt_assert0(simdata->host_nb == 0,
  47               "This is a parallel task. Go to hell.");
  48
  49 #ifdef HAVE_TRACING
  50   TRACE_msg_task_execute_start(task);
  51 #endif
  52
  53   xbt_assert1((!simdata->compute) && (task->simdata->isused == 0),
  54               "This task is executed somewhere else. Go fix your code! %d",
  55               task->simdata->isused);
  56
  57   DEBUG1("Computing on %s", MSG_process_self()->simdata->m_host->name);
  58
  59   if (simdata->computation_amount == 0) {
  60 #ifdef HAVE_TRACING
  61     TRACE_msg_task_execute_end(task);
  62 #endif
  63     return MSG_OK;
  64   }
  65   simdata->isused=1;
  66   simdata->compute =
  67       SIMIX_req_host_execute(task->name, SIMIX_host_self(),
  68                            simdata->computation_amount,
  69                            simdata->priority);
  70 #ifdef HAVE_TRACING
  71   SIMIX_req_set_category(simdata->compute, task->category);
  72 #endif
  73
  74   self->simdata->waiting_action = simdata->compute;
  75   comp_state = SIMIX_req_host_execution_wait(simdata->compute);
  76   self->simdata->waiting_action = NULL;
  77
  78   simdata->isused=0;
  79
  80   DEBUG2("Execution task '%s' finished in state %d", task->name, comp_state);
  81   if (comp_state == SIMIX_DONE) {
  82     /* action ended, set comm and compute = NULL, the actions is already destroyed in the main function */
  83     simdata->computation_amount = 0.0;
  84     simdata->comm = NULL;
  85     simdata->compute = NULL;
  86 #ifdef HAVE_TRACING
  87     TRACE_msg_task_execute_end(task);
  88 #endif
  89     MSG_RETURN(MSG_OK);
  90   } else if (SIMIX_req_host_get_state(SIMIX_host_self()) == 0) {
  91     /* action ended, set comm and compute = NULL, the actions is already destroyed in the main function */
  92     simdata->comm = NULL;
  93     simdata->compute = NULL;
  94 #ifdef HAVE_TRACING
  95     TRACE_msg_task_execute_end(task);
  96 #endif
  97     MSG_RETURN(MSG_HOST_FAILURE);
  98   } else {
  99     /* action ended, set comm and compute = NULL, the actions is already destroyed in the main function */
 100     simdata->comm = NULL;
 101     simdata->compute = NULL;
 102 #ifdef HAVE_TRACING
 103     TRACE_msg_task_execute_end(task);
 104 #endif
 105     MSG_RETURN(MSG_TASK_CANCELLED);
 106   }
 107 }
 108
 109 /** \ingroup m_task_management
 110  * \brief Creates a new #m_task_t (a parallel one....).
 111  *
 112  * A constructor for #m_task_t taking six arguments and returning the
 113  corresponding object.
 114  * \param name a name for the object. It is for user-level information
 115  and can be NULL.
 116  * \param host_nb the number of hosts implied in the parallel task.
 117  * \param host_list an array of \p host_nb m_host_t.
 118  * \param computation_amount an array of \p host_nb
 119  doubles. computation_amount[i] is the total number of operations
 120  that have to be performed on host_list[i].
 121  * \param communication_amount an array of \p host_nb* \p host_nb doubles.
 122  * \param data a pointer to any data may want to attach to the new
 123  object.  It is for user-level information and can be NULL. It can
 124  be retrieved with the function \ref MSG_task_get_data.
 125  * \see m_task_t
 126  * \return The new corresponding object.
 127  */
 128 m_task_t
 129 MSG_parallel_task_create(const char *name, int host_nb,
 130                          const m_host_t * host_list,
 131                          double *computation_amount,
 132                          double *communication_amount, void *data)
 133 {
 134   int i;
 135   simdata_task_t simdata = xbt_new0(s_simdata_task_t, 1);
 136   m_task_t task = xbt_new0(s_m_task_t, 1);
 137   task->simdata = simdata;
 138
 139   /* Task structure */
 140   task->name = xbt_strdup(name);
 141   task->data = data;
 142
 143   /* Simulator Data */
 144   simdata->computation_amount = 0;
 145   simdata->message_size = 0;
 146   simdata->compute = NULL;
 147   simdata->comm = NULL;
 148   simdata->rate = -1.0;
 149   simdata->isused = 0;
 150   simdata->sender = NULL;
 151   simdata->receiver = NULL;
 152   simdata->source = NULL;
 153
 154   simdata->host_nb = host_nb;
 155   simdata->host_list = xbt_new0(smx_host_t, host_nb);
 156   simdata->comp_amount = computation_amount;
 157   simdata->comm_amount = communication_amount;
 158
 159   for (i = 0; i < host_nb; i++)
 160     simdata->host_list[i] = host_list[i]->simdata->smx_host;
 161
 162   return task;
 163 }
 164
 165 MSG_error_t MSG_parallel_task_execute(m_task_t task)
 166 {
 167   simdata_task_t simdata = NULL;
 168   e_smx_state_t comp_state;
 169   m_process_t self = MSG_process_self();
 170   CHECK_HOST();
 171
 172   simdata = task->simdata;
 173
 174   xbt_assert0((!simdata->compute)
 175               && (task->simdata->isused == 0),
 176               "This task is executed somewhere else. Go fix your code!");
 177
 178   xbt_assert0(simdata->host_nb,
 179               "This is not a parallel task. Go to hell.");
 180
 181   DEBUG1("Parallel computing on %s", MSG_process_self()->simdata->m_host->name);
 182
 183   simdata->isused=1;
 184
 185   simdata->compute =
 186       SIMIX_req_host_parallel_execute(task->name, simdata->host_nb,
 187                                   simdata->host_list,
 188                                   simdata->comp_amount,
 189                                   simdata->comm_amount, 1.0, -1.0);
 190   DEBUG1("Parallel execution action created: %p", simdata->compute);
 191
 192   self->simdata->waiting_action = simdata->compute;
 193   comp_state = SIMIX_req_host_execution_wait(simdata->compute);
 194   self->simdata->waiting_action = NULL;
 195
 196   DEBUG2("Finished waiting for execution of action %p, state = %d", simdata->compute, comp_state);
 197
 198   simdata->isused=0;
 199
 200   if (comp_state == SIMIX_DONE) {
 201     /* action ended, set comm and compute = NULL, the actions is already destroyed in the main function */
 202     simdata->computation_amount = 0.0;
 203     simdata->comm = NULL;
 204     simdata->compute = NULL;
 205     MSG_RETURN(MSG_OK);
 206   } else if (SIMIX_req_host_get_state(SIMIX_host_self()) == 0) {
 207     /* action ended, set comm and compute = NULL, the actions is already destroyed in the main function */
 208     simdata->comm = NULL;
 209     simdata->compute = NULL;
 210     MSG_RETURN(MSG_HOST_FAILURE);
 211   } else {
 212     /* action ended, set comm and compute = NULL, the actions is already destroyed in the main function */
 213     simdata->comm = NULL;
 214     simdata->compute = NULL;
 215     MSG_RETURN(MSG_TASK_CANCELLED);
 216   }
 217 }
 218
 219
 220 /** \ingroup msg_gos_functions
 221  * \brief Sleep for the specified number of seconds
 222  *
 223  * Makes the current process sleep until \a time seconds have elapsed.
 224  *
 225  * \param nb_sec a number of second
 226  */
 227 MSG_error_t MSG_process_sleep(double nb_sec)
 228 {
 229   e_smx_state_t state;
 230   /*m_process_t proc = MSG_process_self();*/
 231
 232 #ifdef HAVE_TRACING
 233   TRACE_msg_process_sleep_in(MSG_process_self());
 234 #endif
 235
 236   /* create action to sleep */
 237   state = SIMIX_req_process_sleep(nb_sec);
 238
 239   /*proc->simdata->waiting_action = act_sleep;
 240
 241   FIXME: check if not setting the waiting_action breaks something on msg
 242
 243   proc->simdata->waiting_action = NULL;*/
 244
 245   if (state == SIMIX_DONE) {
 246     if (SIMIX_req_host_get_state(SIMIX_host_self()) == SURF_RESOURCE_OFF) {
 247 #ifdef HAVE_TRACING
 248       TRACE_msg_process_sleep_out(MSG_process_self());
 249 #endif
 250       MSG_RETURN(MSG_HOST_FAILURE);
 251     }
 252   } else {
 253 #ifdef HAVE_TRACING
 254     TRACE_msg_process_sleep_out(MSG_process_self());
 255 #endif
 256     MSG_RETURN(MSG_HOST_FAILURE);
 257   }
 258 #ifdef HAVE_TRACING
 259   TRACE_msg_process_sleep_out(MSG_process_self());
 260 #endif
 261   MSG_RETURN(MSG_OK);
 262 }
 263
 264 /** \ingroup msg_gos_functions
 265  * \brief Listen on \a channel and waits for receiving a task from \a host.
 266  *
 267  * It takes three parameters.
 268  * \param task a memory location for storing a #m_task_t. It will
 269  hold a task when this function will return. Thus \a task should not
 270  be equal to \c NULL and \a *task should be equal to \c NULL. If one of
 271  those two condition does not hold, there will be a warning message.
 272  * \param channel the channel on which the agent should be
 273  listening. This value has to be >=0 and < than the maximal
 274  number of channels fixed with MSG_set_channel_number().
 275  * \param host the host that is to be watched.
 276  * \return #MSG_FATAL if \a task is equal to \c NULL, #MSG_WARNING
 277  if \a *task is not equal to \c NULL, and #MSG_OK otherwise.
 278  */
 279 MSG_error_t
 280 MSG_task_get_from_host(m_task_t * task, m_channel_t channel, m_host_t host)
 281 {
 282   return MSG_task_get_ext(task, channel, -1, host);
 283 }
 284
 285 /** \ingroup msg_gos_functions
 286  * \brief Listen on a channel and wait for receiving a task.
 287  *
 288  * It takes two parameters.
 289  * \param task a memory location for storing a #m_task_t. It will
 290  hold a task when this function will return. Thus \a task should not
 291  be equal to \c NULL and \a *task should be equal to \c NULL. If one of
 292  those two condition does not hold, there will be a warning message.
 293  * \param channel the channel on which the agent should be
 294  listening. This value has to be >=0 and < than the maximal
 295  number of channels fixed with MSG_set_channel_number().
 296  * \return #MSG_FATAL if \a task is equal to \c NULL, #MSG_WARNING
 297  * if \a *task is not equal to \c NULL, and #MSG_OK otherwise.
 298  */
 299 MSG_error_t MSG_task_get(m_task_t * task, m_channel_t channel)
 300 {
 301   return MSG_task_get_with_timeout(task, channel, -1);
 302 }
 303
 304 /** \ingroup msg_gos_functions
 305  * \brief Listen on a channel and wait for receiving a task with a timeout.
 306  *
 307  * It takes three parameters.
 308  * \param task a memory location for storing a #m_task_t. It will
 309  hold a task when this function will return. Thus \a task should not
 310  be equal to \c NULL and \a *task should be equal to \c NULL. If one of
 311  those two condition does not hold, there will be a warning message.
 312  * \param channel the channel on which the agent should be
 313  listening. This value has to be >=0 and < than the maximal
 314  number of channels fixed with MSG_set_channel_number().
 315  * \param max_duration the maximum time to wait for a task before giving
 316  up. In such a case, #MSG_TRANSFER_FAILURE will be returned, \a task
 317  will not be modified and will still be
 318  equal to \c NULL when returning.
 319  * \return #MSG_FATAL if \a task is equal to \c NULL, #MSG_WARNING
 320  if \a *task is not equal to \c NULL, and #MSG_OK otherwise.
 321  */
 322 MSG_error_t
 323 MSG_task_get_with_timeout(m_task_t * task, m_channel_t channel,
 324                           double max_duration)
 325 {
 326   return MSG_task_get_ext(task, channel, max_duration, NULL);
 327 }
 328
 329 /** \defgroup msg_gos_functions MSG Operating System Functions
 330  *  \brief This section describes the functions that can be used
 331  *  by an agent for handling some task.
 332  */
 333
 334 MSG_error_t
 335 MSG_task_get_ext(m_task_t * task, m_channel_t channel, double timeout,
 336                  m_host_t host)
 337 {
 338   xbt_assert1((channel >= 0)
 339               && (channel < msg_global->max_channel), "Invalid channel %d",
 340               channel);
 341
 342   return
 343       MSG_mailbox_get_task_ext(MSG_mailbox_get_by_channel
 344                                (MSG_host_self(), channel), task, host,
 345                                timeout);
 346 }
 347
 348 MSG_error_t
 349 MSG_task_receive_from_host(m_task_t * task, const char *alias,
 350                            m_host_t host)
 351 {
 352   return MSG_task_receive_ext(task, alias, -1, host);
 353 }
 354
 355 MSG_error_t MSG_task_receive(m_task_t * task, const char *alias)
 356 {
 357   return MSG_task_receive_with_timeout(task, alias, -1);
 358 }
 359
 360 MSG_error_t
 361 MSG_task_receive_with_timeout(m_task_t * task, const char *alias,
 362                               double timeout)
 363 {
 364   return MSG_task_receive_ext(task, alias, timeout, NULL);
 365 }
 366
 367 MSG_error_t
 368 MSG_task_receive_ext(m_task_t * task, const char *alias, double timeout,
 369                      m_host_t host)
 370 {
 371   DEBUG1
 372       ("MSG_task_receive_ext: Trying to receive a message on mailbox '%s'",
 373        alias);
 374   return MSG_mailbox_get_task_ext(MSG_mailbox_get_by_alias(alias), task,
 375                                   host, timeout);
 376 }
 377
 378 /** \ingroup msg_gos_functions
 379  * \brief Send a task on a channel.
 380  *
 381  * This function takes two parameter.
 382  * \param task a #m_task_t to send on another location.
 383  * \param alias the channel on which the agent should put this
 384  task. This value has to be >=0 and < than the maximal number of
 385  channels fixed with MSG_set_channel_number().
 386  * \return the msg_comm_t communication.
 387  */
 388 msg_comm_t MSG_task_isend(m_task_t task, const char *alias)
 389 {
 390   simdata_task_t t_simdata = NULL;
 391   m_process_t process = MSG_process_self();
 392   msg_mailbox_t mailbox = MSG_mailbox_get_by_alias(alias);
 393
 394   CHECK_HOST();
 395
 396   /* FIXME: these functions are not tracable */
 397
 398   /* Prepare the task to send */
 399   t_simdata = task->simdata;
 400   t_simdata->sender = process;
 401   t_simdata->source = MSG_host_self();
 402
 403   xbt_assert0(t_simdata->isused == 0,
 404               "This task is still being used somewhere else. You cannot send it now. Go fix your code!");
 405
 406   t_simdata->isused=1;
 407   msg_global->sent_msg++;
 408
 409   /* Send it by calling SIMIX network layer */
 410   t_simdata->comm =
 411     SIMIX_req_comm_isend(mailbox, t_simdata->message_size,
 412                          t_simdata->rate, task, sizeof(void *), NULL, NULL);
 413   return t_simdata->comm;
 414 }
 415
 416 /** \ingroup msg_gos_functions
 417  * \brief Listen on a channel for receiving a task from an asynchronous communication.
 418  *
 419  * It takes two parameters.
 420  * \param task a memory location for storing a #m_task_t.
 421  * \param alias the channel on which the agent should be
 422  listening. This value has to be >=0 and < than the maximal
 423  number of channels fixed with MSG_set_channel_number().
 424  * \return the msg_comm_t communication.
 425  */
 426 msg_comm_t MSG_task_irecv(m_task_t * task, const char *alias)
 427 {
 428   smx_rdv_t rdv = MSG_mailbox_get_by_alias(alias);
 429
 430   CHECK_HOST();
 431
 432   /* FIXME: these functions are not tracable */
 433
 434   /* Sanity check */
 435   xbt_assert0(task, "Null pointer for the task storage");
 436
 437   if (*task)
 438     CRITICAL0
 439         ("MSG_task_get() was asked to write in a non empty task struct.");
 440
 441   /* Try to receive it by calling SIMIX network layer */
 442   return SIMIX_req_comm_irecv(rdv, task, NULL, NULL, NULL);
 443 }
 444
 445 /** \ingroup msg_gos_functions
 446  * \brief Returns whether a communication is finished.
 447  * \param comm the communication to test
 448  * \return TRUE if the communication is finished
 449  * (but it may have failed, use MSG_comm_get_status() to know its status)
 450  * or FALSE if the communication is not finished yet
 451  * If the status is FALSE, don't forget to use MSG_process_sleep() after the test.
 452  */
 453 int MSG_comm_test(msg_comm_t comm)
 454 {
 455   xbt_ex_t e;
 456   int finished = 0;
 457   TRY {
 458     finished = SIMIX_req_comm_test(comm);
 459   }
 460   CATCH(e) {
 461     switch (e.category) {
 462
 463       case host_error:
 464       case network_error:
 465       case timeout_error:
 466         finished = 1;
 467         break;
 468
 469       default:
 470         RETHROW;
 471     }
 472     xbt_ex_free(e);
 473   }
 474   return finished;
 475 }
 476
 477 /** \ingroup msg_gos_functions
 478  * \brief This function checks if a communication is finished
 479  * \param comms a vector of communications
 480  * \return the position of the finished communication if any
 481  * (but it may have failed, use MSG_comm_get_status() to know its status),
 482  * or -1 if none is finished
 483  */
 484 int MSG_comm_testany(xbt_dynar_t comms)
 485 {
 486   xbt_ex_t e;
 487   int finished_index = -1;
 488   TRY {
 489     finished_index = SIMIX_req_comm_testany(comms);
 490   }
 491   CATCH(e) {
 492     switch (e.category) {
 493
 494       case host_error:
 495       case network_error:
 496       case timeout_error:
 497         finished_index = e.value;
 498         break;
 499
 500       default:
 501         RETHROW;
 502     }
 503     xbt_ex_free(e);
 504   }
 505   return finished_index;
 506 }
 507
 508 /** \ingroup msg_gos_functions
 509  * \brief After received TRUE to MSG_comm_test(), the communication should be destroyed.
 510  *
 511  * It takes one parameter.
 512  * \param comm the communication to destroy.
 513  */
 514 void MSG_comm_destroy(msg_comm_t comm)
 515 {
 516   if (SIMIX_req_comm_get_src_proc(comm) != SIMIX_process_self()
 517       && MSG_comm_get_status(comm) == MSG_OK) {
 518     m_task_t task;
 519     task = (m_task_t) SIMIX_req_comm_get_src_buff(comm);
 520     task->simdata->isused=0;
 521   }
 522   SIMIX_req_comm_destroy(comm);
 523 }
 524
 525 /** \ingroup msg_gos_functions
 526  * \brief Wait for the completion of a communication.
 527  *
 528  * It takes two parameters.
 529  * \param comm the communication to wait.
 530  * \param timeout Wait until the communication terminates or the timeout occurs
 531  * \return MSG_error_t
 532  */
 533 MSG_error_t MSG_comm_wait(msg_comm_t comm, double timeout)
 534 {
 535   xbt_ex_t e;
 536   MSG_error_t res = MSG_OK;
 537   TRY {
 538     SIMIX_req_comm_wait(comm, timeout);
 539
 540     if (SIMIX_req_comm_get_src_proc(comm) != SIMIX_process_self()) {
 541       m_task_t task;
 542       task = (m_task_t) SIMIX_req_comm_get_src_buff(comm);
 543       task->simdata->isused=0;
 544     }
 545
 546     /* FIXME: these functions are not tracable */
 547   }
 548   CATCH(e) {
 549     switch (e.category) {
 550     case host_error:
 551       res = MSG_HOST_FAILURE;
 552       break;
 553     case network_error:
 554       res = MSG_TRANSFER_FAILURE;
 555       break;
 556     case timeout_error:
 557       res = MSG_TIMEOUT;
 558       break;
 559     default:
 560       RETHROW;
 561     }
 562     xbt_ex_free(e);
 563   }
 564   return res;
 565 }
 566
 567 /** \ingroup msg_gos_functions
 568 * \brief This function is called by a sender and permit to wait for each communication
 569 *
 570 * It takes three parameters.
 571 * \param comm a vector of communication
 572 * \param nb_elem is the size of the comm vector
 573 * \param timeout for each call of  MSG_comm_wait
 574 */
 575 void MSG_comm_waitall(msg_comm_t * comm, int nb_elem, double timeout)
 576 {
 577   int i = 0;
 578   for (i = 0; i < nb_elem; i++) {
 579     MSG_comm_wait(comm[i], timeout);
 580   }
 581 }
 582
 583 /** \ingroup msg_gos_functions
 584 * \brief This function wait for the first completed communication
 585 *
 586 * It takes on parameter.
 587 * \param comms a vector of communication
 588 * \return the position of the completed communication from the xbt_dynar_t.
 589 */
 590 int MSG_comm_waitany(xbt_dynar_t comms)
 591 {
 592   xbt_ex_t e;
 593   int finished_index = -1;
 594   TRY {
 595     finished_index = SIMIX_req_comm_waitany(comms);
 596   }
 597   CATCH(e) {
 598     switch (e.category) {
 599
 600       case host_error:
 601       case network_error:
 602       case timeout_error:
 603         finished_index = e.value;
 604       default:
 605         RETHROW;
 606     }
 607     xbt_ex_free(e);
 608   }
 609   return finished_index;
 610 }
 611
 612 /**
 613  * \ingroup msg_gos_functions
 614  * \brief Returns the error (if any) that occured during a finished communication.
 615  * \param comm a finished communication
 616  * \return the status of the communication, or MSG_OK if the communication
 617  * was successfully completed
 618  */
 619 MSG_error_t MSG_comm_get_status(msg_comm_t comm) {
 620
 621   MSG_error_t result;
 622   e_smx_state_t smx_state = SIMIX_req_comm_get_state(comm);
 623
 624   switch (smx_state) {
 625
 626     case SIMIX_CANCELED:
 627       result = MSG_TASK_CANCELLED;
 628       break;
 629
 630     case SIMIX_FAILED:
 631     case SIMIX_SRC_HOST_FAILURE:
 632     case SIMIX_DST_HOST_FAILURE:
 633       result = MSG_HOST_FAILURE;
 634       break;
 635
 636     case SIMIX_LINK_FAILURE:
 637       result = MSG_TRANSFER_FAILURE;
 638       break;
 639
 640     case SIMIX_SRC_TIMEOUT:
 641     case SIMIX_DST_TIMEOUT:
 642       result = MSG_TIMEOUT;
 643       break;
 644
 645     default:
 646       result = MSG_OK;
 647       break;
 648   }
 649   return result;
 650 }
 651
 652 m_task_t MSG_comm_get_task(msg_comm_t comm)
 653 {
 654   xbt_assert0(comm, "Invalid parameters");
 655   return (m_task_t) SIMIX_req_comm_get_src_buff(comm);
 656 }
 657
 658 /** \ingroup msg_gos_functions
 659  * \brief Put a task on a channel of an host and waits for the end of the
 660  * transmission.
 661  *
 662  * This function is used for describing the behavior of an agent. It
 663  * takes three parameter.
 664  * \param task a #m_task_t to send on another location. This task
 665  will not be usable anymore when the function will return. There is
 666  no automatic task duplication and you have to save your parameters
 667  before calling this function. Tasks are unique and once it has been
 668  sent to another location, you should not access it anymore. You do
 669  not need to call MSG_task_destroy() but to avoid using, as an
 670  effect of inattention, this task anymore, you definitely should
 671  renitialize it with #MSG_TASK_UNINITIALIZED. Note that this task
 672  can be transfered iff it has been correctly created with
 673  MSG_task_create().
 674  * \param dest the destination of the message
 675  * \param channel the channel on which the agent should put this
 676  task. This value has to be >=0 and < than the maximal number of
 677  channels fixed with MSG_set_channel_number().
 678  * \return #MSG_FATAL if \a task is not properly initialized and
 679  * #MSG_OK otherwise. Returns #MSG_HOST_FAILURE if the host on which
 680  * this function was called was shut down. Returns
 681  * #MSG_TRANSFER_FAILURE if the transfer could not be properly done
 682  * (network failure, dest failure)
 683  */
 684 MSG_error_t MSG_task_put(m_task_t task, m_host_t dest, m_channel_t channel)
 685 {
 686   return MSG_task_put_with_timeout(task, dest, channel, -1.0);
 687 }
 688
 689 /** \ingroup msg_gos_functions
 690  * \brief Does exactly the same as MSG_task_put but with a bounded transmition
 691  * rate.
 692  *
 693  * \sa MSG_task_put
 694  */
 695 MSG_error_t
 696 MSG_task_put_bounded(m_task_t task, m_host_t dest, m_channel_t channel,
 697                      double maxrate)
 698 {
 699   task->simdata->rate = maxrate;
 700   return MSG_task_put(task, dest, channel);
 701 }
 702
 703 /** \ingroup msg_gos_functions \brief Put a task on a channel of an
 704  * host (with a timeout on the waiting of the destination host) and
 705  * waits for the end of the transmission.
 706  *
 707  * This function is used for describing the behavior of an agent. It
 708  * takes four parameter.
 709  * \param task a #m_task_t to send on another location. This task
 710  will not be usable anymore when the function will return. There is
 711  no automatic task duplication and you have to save your parameters
 712  before calling this function. Tasks are unique and once it has been
 713  sent to another location, you should not access it anymore. You do
 714  not need to call MSG_task_destroy() but to avoid using, as an
 715  effect of inattention, this task anymore, you definitely should
 716  renitialize it with #MSG_TASK_UNINITIALIZED. Note that this task
 717  can be transfered iff it has been correctly created with
 718  MSG_task_create().
 719  * \param dest the destination of the message
 720  * \param channel the channel on which the agent should put this
 721  task. This value has to be >=0 and < than the maximal number of
 722  channels fixed with MSG_set_channel_number().
 723  * \param timeout the maximum time to wait for a task before giving
 724  up. In such a case, #MSG_TRANSFER_FAILURE will be returned, \a task
 725  will not be modified
 726  * \return #MSG_FATAL if \a task is not properly initialized and
 727 #MSG_OK otherwise. Returns #MSG_HOST_FAILURE if the host on which
 728 this function was called was shut down. Returns
 729 #MSG_TRANSFER_FAILURE if the transfer could not be properly done
 730 (network failure, dest failure, timeout...)
 731  */
 732 MSG_error_t
 733 MSG_task_put_with_timeout(m_task_t task, m_host_t dest,
 734                           m_channel_t channel, double timeout)
 735 {
 736   xbt_assert1((channel >= 0)
 737               && (channel < msg_global->max_channel), "Invalid channel %d",
 738               channel);
 739
 740   DEBUG1("MSG_task_put_with_timout: Trying to send a task to '%s'", dest->name);
 741   return
 742       MSG_mailbox_put_with_timeout(MSG_mailbox_get_by_channel
 743                                    (dest, channel), task, timeout);
 744 }
 745
 746 MSG_error_t MSG_task_send(m_task_t task, const char *alias)
 747 {
 748   DEBUG1("MSG_task_send: Trying to send a message on mailbox '%s'", alias);
 749   return MSG_task_send_with_timeout(task, alias, -1);
 750 }
 751
 752
 753 MSG_error_t
 754 MSG_task_send_bounded(m_task_t task, const char *alias, double maxrate)
 755 {
 756   task->simdata->rate = maxrate;
 757   return MSG_task_send(task, alias);
 758 }
 759
 760
 761 MSG_error_t
 762 MSG_task_send_with_timeout(m_task_t task, const char *alias,
 763                            double timeout)
 764 {
 765   return MSG_mailbox_put_with_timeout(MSG_mailbox_get_by_alias(alias),
 766                                       task, timeout);
 767 }
 768
 769 int MSG_task_listen(const char *alias)
 770 {
 771   CHECK_HOST();
 772
 773   return !MSG_mailbox_is_empty(MSG_mailbox_get_by_alias(alias));
 774 }
 775
 776 /** \ingroup msg_gos_functions
 777  * \brief Test whether there is a pending communication on a channel.
 778  *
 779  * It takes one parameter.
 780  * \param channel the channel on which the agent should be
 781  listening. This value has to be >=0 and < than the maximal
 782  number of channels fixed with MSG_set_channel_number().
 783  * \return 1 if there is a pending communication and 0 otherwise
 784  */
 785 int MSG_task_Iprobe(m_channel_t channel)
 786 {
 787   xbt_assert1((channel >= 0)
 788               && (channel < msg_global->max_channel), "Invalid channel %d",
 789               channel);
 790
 791   CHECK_HOST();
 792
 793   return
 794       !MSG_mailbox_is_empty(MSG_mailbox_get_by_channel
 795                             (MSG_host_self(), channel));
 796 }
 797
 798 /** \ingroup msg_gos_functions
 799
 800  * \brief Return the number of tasks waiting to be received on a \a
 801  channel and sent by \a host.
 802  *
 803  * It takes two parameters.
 804  * \param channel the channel on which the agent should be
 805  listening. This value has to be >=0 and < than the maximal
 806  number of channels fixed with MSG_set_channel_number().
 807  * \param host the host that is to be watched.
 808  * \return the number of tasks waiting to be received on \a channel
 809  and sent by \a host.
 810  */
 811 int MSG_task_probe_from_host(int channel, m_host_t host)
 812 {
 813   xbt_assert1((channel >= 0)
 814               && (channel < msg_global->max_channel), "Invalid channel %d",
 815               channel);
 816
 817   CHECK_HOST();
 818
 819   return
 820       MSG_mailbox_get_count_host_waiting_tasks(MSG_mailbox_get_by_channel
 821                                                (MSG_host_self(), channel),
 822                                                host);
 823
 824 }
 825
 826 int MSG_task_listen_from_host(const char *alias, m_host_t host)
 827 {
 828   CHECK_HOST();
 829
 830   return
 831       MSG_mailbox_get_count_host_waiting_tasks(MSG_mailbox_get_by_alias
 832                                                (alias), host);
 833 }
 834
 835 /** \ingroup msg_gos_functions
 836  * \brief Test whether there is a pending communication on a channel, and who sent it.
 837  *
 838  * It takes one parameter.
 839  * \param channel the channel on which the agent should be
 840  listening. This value has to be >=0 and < than the maximal
 841  number of channels fixed with MSG_set_channel_number().
 842  * \return -1 if there is no pending communication and the PID of the process who sent it otherwise
 843  */
 844 int MSG_task_probe_from(m_channel_t channel)
 845 {
 846   m_task_t task;
 847
 848   CHECK_HOST();
 849
 850   xbt_assert1((channel >= 0)
 851               && (channel < msg_global->max_channel), "Invalid channel %d",
 852               channel);
 853
 854   if (NULL ==
 855       (task =
 856        MSG_mailbox_get_head(MSG_mailbox_get_by_channel
 857                             (MSG_host_self(), channel))))
 858     return -1;
 859
 860   return MSG_process_get_PID(task->simdata->sender);
 861 }
 862
 863 int MSG_task_listen_from(const char *alias)
 864 {
 865   m_task_t task;
 866
 867   CHECK_HOST();
 868
 869   if (NULL ==
 870       (task = MSG_mailbox_get_head(MSG_mailbox_get_by_alias(alias))))
 871     return -1;
 872
 873   return MSG_process_get_PID(task->simdata->sender);
 874 }