src/msg/msg_mailbox.h

   1 /* Copyright (c) 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 #ifndef MSG_MAILBOX_H
   8 #define MSG_MAILBOX_H
   9
  10 #include "xbt/fifo.h"
  11 #include "simgrid/simix.h"
  12 #include "msg/datatypes.h"
  13
  14
  15 SG_BEGIN_DECL()
  16 #define MAX_ALIAS_NAME  ((size_t)260)
  17
  18 /*! \brief MSG_mailbox_new - create a new mailbox.
  19  *
  20  * The function MSG_mailbox_new creates a new mailbox identified by the key specified
  21  * by the parameter alias and add it in the global dictionary.
  22  *
  23  * \param alias    The alias of the mailbox to create.
  24  *
  25  * \return    The newly created mailbox.
  26  */
  27 XBT_PUBLIC(msg_mailbox_t)
  28     MSG_mailbox_new(const char *alias);
  29
  30 void MSG_mailbox_free(void *mailbox);
  31
  32 /* \brief MSG_mailbox_free - release a mailbox from the memory.
  33  *
  34  * The function MSG_mailbox_free release a mailbox from the memory but does
  35  * not remove it from the dictionary.
  36  *
  37  * \param mailbox  The mailbox to release.
  38  *
  39  * \see      MSG_mailbox_destroy.
  40  */
  41 void MSG_mailbox_free(void *mailbox);
  42
  43 /* \brief MSG_set_rate_before_read - set a rate before receiving a task
  44  *
  45  * \param mailbox  The mailbox to release.
  46  * \param rate     The new rate
  47  */
  48 double MSG_set_rate_before_read(msg_mailbox_t mailbox, double rate);
  49
  50 /* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
  51  *
  52  * The function MSG_mailbox_get_by_alias returns the mailbox associated with
  53  * the key specified by the parameter alias. If the mailbox does not exists,
  54  * the function create it.
  55  *
  56  * \param alias    The alias of the mailbox to return.
  57  *
  58  * \return  The mailbox associated with the alias specified as parameter
  59  *    or a new mailbox if the key does not match.
  60  */
  61 XBT_PUBLIC(msg_mailbox_t)
  62     MSG_mailbox_get_by_alias(const char *alias);
  63
  64 /*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
  65  *
  66  * The function MSG_mailbox_is_empty tests if a mailbox is empty
  67  * (contains no msg task).
  68  *
  69  * \param mailbox  The mailbox to get test.
  70  *
  71  * \return  The function returns 1 if the mailbox is empty. Otherwise the function
  72  *    returns 0.
  73  */
  74 XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
  75
  76 /* \brief MSG_mailbox_set_async - set a mailbox as eager
  77  *
  78  * The function MSG_mailbox_set_async sets the mailbox to a permanent receiver mode
  79  * Messages sent to this mailbox will then be sent just after the send is issued,
  80  * without waiting for the corresponding receive.
  81  *
  82  * This call should be done before issuing any receive, and on the receiver's side only
  83  *
  84  * \param alias    The alias of the mailbox to modify.
  85  *
  86  */
  87 void MSG_mailbox_set_async(const char *alias);
  88
  89 /*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
  90  *
  91  * The MSG_mailbox_get_head returns the task at the head of the mailbox.
  92  * This function does not remove the task from the mailbox (contrary to
  93  * the function MSG_mailbox_pop_head).
  94  *
  95  * \param mailbox  The mailbox concerned by the operation.
  96  *
  97  * \return    The task at the head of the mailbox.
  98  */
  99 XBT_PUBLIC(msg_task_t)
 100     MSG_mailbox_get_head(msg_mailbox_t mailbox);
 101
 102 /*! \brief MSG_mailbox_get_count_host_waiting_tasks - Return the number of tasks
 103    waiting to be received in a mailbox and sent by a host.
 104  *
 105  * \param mailbox  The mailbox concerned by the operation.
 106  * \param host    The msg host containing the processes that have sended the
 107  *      tasks.
 108  *
 109  * \return    The number of tasks in the mailbox specified by the
 110  *      parameter mailbox and sended by all the processes located
 111  *      on the host specified by the parameter host.
 112  */
 113 XBT_PUBLIC(int)
 114 MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
 115                                          msg_host_t host);
 116
 117 #ifdef MSG_USE_DEPRECATED
 118 /* \brief MSG_mailbox_get_by_channel - get a mailbox of the specified host from its channel.
 119  *
 120  * The function MSG_mailbox_get_by_channel returns the mailbox of the
 121  * specified host from the channel specified by the parameter
 122  * channel. If the mailbox does not exists, the function fails.
 123  *
 124  * \param host      The host containing he mailbox to get.
 125  * \param channel   The channel used to identify the mailbox.
 126  *
 127  * \return The mailbox of the specified host associated the channel
 128  *         specified as parameter.
 129  *
 130  */
 131 XBT_PUBLIC(msg_mailbox_t)
 132     MSG_mailbox_get_by_channel(msg_host_t host, m_channel_t channel);
 133 #endif
 134
 135 SG_END_DECL()
 136 #endif                          /* !MSG_MAILBOX_H */