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 *),
 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);
 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     SIMIX_req_comm_destroy(comm);
 502
 503     /* FIXME: these functions are not tracable */
 504   }
 505   CATCH(e) {
 506     switch (e.category) {
 507     case host_error:
 508       res = MSG_HOST_FAILURE;
 509       break;
 510     case network_error:
 511       res = MSG_TRANSFER_FAILURE;
 512       break;
 513     case timeout_error:
 514       res = MSG_TIMEOUT;
 515       break;
 516     default:
 517       xbt_die(bprintf("Unhandled SIMIX network exception: %s", e.msg));
 518     }
 519     xbt_ex_free(e);
 520   }
 521   return res;
 522 }
 523
 524 /** \ingroup msg_gos_functions
 525 * \brief This function is called by a sender and permit to wait for each communication
 526 *
 527 * It takes three parameters.
 528 * \param comm a vector of communication
 529 * \param nb_elem is the size of the comm vector
 530 * \param timeout for each call of  MSG_comm_wait
 531 */
 532 void MSG_comm_waitall(msg_comm_t * comm, int nb_elem, double timeout)
 533 {
 534   int i = 0;
 535   for (i = 0; i < nb_elem; i++) {
 536     MSG_comm_wait(comm[i], timeout);
 537   }
 538 }
 539
 540 /** \ingroup msg_gos_functions
 541 * \brief This function wait for the first completed communication
 542 *
 543 * It takes on parameter.
 544 * \param comms a vector of communication
 545 * \return the position of the completed communication from the xbt_dynar_t.
 546 */
 547 int MSG_comm_waitany(xbt_dynar_t comms)
 548 {
 549   return SIMIX_req_comm_waitany(comms);
 550 }
 551
 552 /** \ingroup msg_gos_functions
 553 * \brief This function wait for the first completed communication
 554 *
 555 * It takes on parameter.
 556 * \param comms a vector of communication
 557 * \return the position of the completed communication, if any, or -1 if none was completed
 558 */
 559 int MSG_comm_testany(xbt_dynar_t comms)
 560 {
 561   return SIMIX_req_comm_testany(comms);
 562 }
 563
 564 m_task_t MSG_comm_get_task(msg_comm_t comm)
 565 {
 566   xbt_assert0(comm, "Invalid parameters");
 567   return (m_task_t) SIMIX_req_comm_get_src_buff(comm);
 568 }
 569
 570 /** \ingroup msg_gos_functions
 571  * \brief Put a task on a channel of an host and waits for the end of the
 572  * transmission.
 573  *
 574  * This function is used for describing the behavior of an agent. It
 575  * takes three parameter.
 576  * \param task a #m_task_t to send on another location. This task
 577  will not be usable anymore when the function will return. There is
 578  no automatic task duplication and you have to save your parameters
 579  before calling this function. Tasks are unique and once it has been
 580  sent to another location, you should not access it anymore. You do
 581  not need to call MSG_task_destroy() but to avoid using, as an
 582  effect of inattention, this task anymore, you definitely should
 583  renitialize it with #MSG_TASK_UNINITIALIZED. Note that this task
 584  can be transfered iff it has been correctly created with
 585  MSG_task_create().
 586  * \param dest the destination of the message
 587  * \param channel the channel on which the agent should put this
 588  task. This value has to be >=0 and < than the maximal number of
 589  channels fixed with MSG_set_channel_number().
 590  * \return #MSG_FATAL if \a task is not properly initialized and
 591  * #MSG_OK otherwise. Returns #MSG_HOST_FAILURE if the host on which
 592  * this function was called was shut down. Returns
 593  * #MSG_TRANSFER_FAILURE if the transfer could not be properly done
 594  * (network failure, dest failure)
 595  */
 596 MSG_error_t MSG_task_put(m_task_t task, m_host_t dest, m_channel_t channel)
 597 {
 598   return MSG_task_put_with_timeout(task, dest, channel, -1.0);
 599 }
 600
 601 /** \ingroup msg_gos_functions
 602  * \brief Does exactly the same as MSG_task_put but with a bounded transmition
 603  * rate.
 604  *
 605  * \sa MSG_task_put
 606  */
 607 MSG_error_t
 608 MSG_task_put_bounded(m_task_t task, m_host_t dest, m_channel_t channel,
 609                      double maxrate)
 610 {
 611   task->simdata->rate = maxrate;
 612   return MSG_task_put(task, dest, channel);
 613 }
 614
 615 /** \ingroup msg_gos_functions \brief Put a task on a channel of an
 616  * host (with a timeout on the waiting of the destination host) and
 617  * waits for the end of the transmission.
 618  *
 619  * This function is used for describing the behavior of an agent. It
 620  * takes four parameter.
 621  * \param task a #m_task_t to send on another location. This task
 622  will not be usable anymore when the function will return. There is
 623  no automatic task duplication and you have to save your parameters
 624  before calling this function. Tasks are unique and once it has been
 625  sent to another location, you should not access it anymore. You do
 626  not need to call MSG_task_destroy() but to avoid using, as an
 627  effect of inattention, this task anymore, you definitely should
 628  renitialize it with #MSG_TASK_UNINITIALIZED. Note that this task
 629  can be transfered iff it has been correctly created with
 630  MSG_task_create().
 631  * \param dest the destination of the message
 632  * \param channel the channel on which the agent should put this
 633  task. This value has to be >=0 and < than the maximal number of
 634  channels fixed with MSG_set_channel_number().
 635  * \param timeout the maximum time to wait for a task before giving
 636  up. In such a case, #MSG_TRANSFER_FAILURE will be returned, \a task
 637  will not be modified
 638  * \return #MSG_FATAL if \a task is not properly initialized and
 639 #MSG_OK otherwise. Returns #MSG_HOST_FAILURE if the host on which
 640 this function was called was shut down. Returns
 641 #MSG_TRANSFER_FAILURE if the transfer could not be properly done
 642 (network failure, dest failure, timeout...)
 643  */
 644 MSG_error_t
 645 MSG_task_put_with_timeout(m_task_t task, m_host_t dest,
 646                           m_channel_t channel, double timeout)
 647 {
 648   xbt_assert1((channel >= 0)
 649               && (channel < msg_global->max_channel), "Invalid channel %d",
 650               channel);
 651
 652   DEBUG1("MSG_task_put_with_timout: Trying to send a task to '%s'", dest->name);
 653   return
 654       MSG_mailbox_put_with_timeout(MSG_mailbox_get_by_channel
 655                                    (dest, channel), task, timeout);
 656 }
 657
 658 MSG_error_t MSG_task_send(m_task_t task, const char *alias)
 659 {
 660   DEBUG1("MSG_task_send: Trying to send a message on mailbox '%s'", alias);
 661   return MSG_task_send_with_timeout(task, alias, -1);
 662 }
 663
 664
 665 MSG_error_t
 666 MSG_task_send_bounded(m_task_t task, const char *alias, double maxrate)
 667 {
 668   task->simdata->rate = maxrate;
 669   return MSG_task_send(task, alias);
 670 }
 671
 672
 673 MSG_error_t
 674 MSG_task_send_with_timeout(m_task_t task, const char *alias,
 675                            double timeout)
 676 {
 677   return MSG_mailbox_put_with_timeout(MSG_mailbox_get_by_alias(alias),
 678                                       task, timeout);
 679 }
 680
 681 int MSG_task_listen(const char *alias)
 682 {
 683   CHECK_HOST();
 684
 685   return !MSG_mailbox_is_empty(MSG_mailbox_get_by_alias(alias));
 686 }
 687
 688 /** \ingroup msg_gos_functions
 689  * \brief Test whether there is a pending communication on a channel.
 690  *
 691  * It takes one parameter.
 692  * \param channel the channel on which the agent should be
 693  listening. This value has to be >=0 and < than the maximal
 694  number of channels fixed with MSG_set_channel_number().
 695  * \return 1 if there is a pending communication and 0 otherwise
 696  */
 697 int MSG_task_Iprobe(m_channel_t channel)
 698 {
 699   xbt_assert1((channel >= 0)
 700               && (channel < msg_global->max_channel), "Invalid channel %d",
 701               channel);
 702
 703   CHECK_HOST();
 704
 705   return
 706       !MSG_mailbox_is_empty(MSG_mailbox_get_by_channel
 707                             (MSG_host_self(), channel));
 708 }
 709
 710 /** \ingroup msg_gos_functions
 711
 712  * \brief Return the number of tasks waiting to be received on a \a
 713  channel and sent by \a host.
 714  *
 715  * It takes two parameters.
 716  * \param channel the channel on which the agent should be
 717  listening. This value has to be >=0 and < than the maximal
 718  number of channels fixed with MSG_set_channel_number().
 719  * \param host the host that is to be watched.
 720  * \return the number of tasks waiting to be received on \a channel
 721  and sent by \a host.
 722  */
 723 int MSG_task_probe_from_host(int channel, m_host_t host)
 724 {
 725   xbt_assert1((channel >= 0)
 726               && (channel < msg_global->max_channel), "Invalid channel %d",
 727               channel);
 728
 729   CHECK_HOST();
 730
 731   return
 732       MSG_mailbox_get_count_host_waiting_tasks(MSG_mailbox_get_by_channel
 733                                                (MSG_host_self(), channel),
 734                                                host);
 735
 736 }
 737
 738 int MSG_task_listen_from_host(const char *alias, m_host_t host)
 739 {
 740   CHECK_HOST();
 741
 742   return
 743       MSG_mailbox_get_count_host_waiting_tasks(MSG_mailbox_get_by_alias
 744                                                (alias), host);
 745 }
 746
 747 /** \ingroup msg_gos_functions
 748  * \brief Test whether there is a pending communication on a channel, and who sent it.
 749  *
 750  * It takes one parameter.
 751  * \param channel the channel on which the agent should be
 752  listening. This value has to be >=0 and < than the maximal
 753  number of channels fixed with MSG_set_channel_number().
 754  * \return -1 if there is no pending communication and the PID of the process who sent it otherwise
 755  */
 756 int MSG_task_probe_from(m_channel_t channel)
 757 {
 758   m_task_t task;
 759
 760   CHECK_HOST();
 761
 762   xbt_assert1((channel >= 0)
 763               && (channel < msg_global->max_channel), "Invalid channel %d",
 764               channel);
 765
 766   if (NULL ==
 767       (task =
 768        MSG_mailbox_get_head(MSG_mailbox_get_by_channel
 769                             (MSG_host_self(), channel))))
 770     return -1;
 771
 772   return MSG_process_get_PID(task->simdata->sender);
 773 }
 774
 775 int MSG_task_listen_from(const char *alias)
 776 {
 777   m_task_t task;
 778
 779   CHECK_HOST();
 780
 781   if (NULL ==
 782       (task = MSG_mailbox_get_head(MSG_mailbox_get_by_alias(alias))))
 783     return -1;
 784
 785   return MSG_process_get_PID(task->simdata->sender);
 786 }