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