src/msg/mailbox.h

   1 #ifndef SMX_MAILBOX_H
   2 #define SMX_MAILBOX_H
   3
   4 #include "xbt/fifo.h"
   5 #include "simix/private.h"
   6 #include "msg/datatypes.h"
   7
   8 SG_BEGIN_DECL()
   9 #define MAX_ALIAS_NAME  ((size_t)260)
  10 /*
  11  * Initialization of the mailbox module.
  12  */
  13      void MSG_mailbox_mod_init(void);
  14
  15 /*
  16  * Terminaison of the mailbox module.
  17  */
  18      void MSG_mailbox_mod_exit(void);
  19
  20
  21 /*! \brief MSG_mailbox_new - create a new mailbox.
  22  *
  23  * The function MSG_mailbox_new creates a new mailbox identified by the key specified
  24  * by the parameter alias and add it in the global dictionary.
  25  *
  26  * \param alias         The alias of the mailbox to create.
  27  *
  28  * \return              The newly created mailbox.
  29  */
  30 XBT_PUBLIC(msg_mailbox_t)
  31   MSG_mailbox_new(const char *alias);
  32
  33 /*! \brief MSG_mailbox_create - create a new mailbox.
  34  *
  35  * The function MSG_mailbox_new creates a new mailbox identified by
  36  * the key specified by the parameter alias and add it in the global
  37  * dictionary but doesn't add it in the global dictionary. Typicaly,
  38  * this type of mailbox is associated with a channel.
  39  *
  40  * \param alias         The alias of the mailbox to create.
  41  *
  42  * \return              The newly created mailbox.
  43  */
  44      msg_mailbox_t MSG_mailbox_create(const char *alias);
  45
  46 /* \brief MSG_mailbox_free - release a mailbox from the memory.
  47  *
  48  * The function MSG_mailbox_free release a mailbox from the memory but does
  49  * not remove it from the dictionary.
  50  *
  51  * \param mailbox       The mailbox to release.
  52  *
  53  * \see                 MSG_mailbox_destroy.
  54  */
  55      void MSG_mailbox_free(void *mailbox);
  56
  57 /* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
  58  *
  59  * The function MSG_mailbox_get_by_alias returns the mailbox associated with
  60  * the key specified by the parameter alias. If the mailbox does not exists,
  61  * the function create it.
  62  *
  63  * \param alias         The alias of the mailbox to return.
  64  *
  65  * \return      The mailbox associated with the alias specified as parameter
  66  *              or a new mailbox if the key does not match.
  67  */
  68 XBT_PUBLIC(msg_mailbox_t)
  69   MSG_mailbox_get_by_alias(const char *alias);
  70
  71 /* \brief MSG_mailbox_get_by_channel - get a mailbox of the specified host from its channel.
  72  *
  73  * The function MSG_mailbox_get_by_channel returns the mailbox of the
  74  * specified host from the channel specified by the parameter
  75  * channel. If the mailbox does not exists, the function fails.
  76  *
  77  * \param host          The host containing he mailbox to get.
  78  * \param channel       The channel used to identify the mailbox.
  79  *
  80  * \return The mailbox of the specified host associated the channel
  81  *         specified as parameter.
  82  *
  83  */
  84 XBT_PUBLIC(msg_mailbox_t)
  85   MSG_mailbox_get_by_channel(m_host_t host, m_channel_t channel);
  86
  87 /*! \brief MSG_mailbox_get_alias - get the alias associated with the mailbox.
  88  *
  89  * The function MSG_mailbox_get_alias returns the alias of the mailbox specified
  90  * by the parameter mailbox.
  91  *
  92  * \param mailbox       The mailbox to get the alias.
  93  *
  94  * \return      The alias of the mailbox specified by the parameter mailbox.
  95  */
  96 XBT_PUBLIC(const char *) MSG_mailbox_get_alias(msg_mailbox_t mailbox);
  97
  98 /*! \brief MSG_mailbox_get_cond - get the simix condition of a mailbox.
  99  *
 100  * The function MSG_mailbox_get_cond returns the condition of the
 101  * mailbox specified by the parameter mailbox.
 102  *
 103  * \param mailbox       The mailbox to get the condition.
 104  *
 105  * \return The simix condition of the mailbox specified by the parameter mailbox.
 106  */
 107 XBT_PUBLIC(smx_cond_t)
 108   MSG_mailbox_get_cond(msg_mailbox_t mailbox);
 109
 110 /*! \brief MSG_mailbox_set_cond - set the simix condition of a mailbox.
 111  *
 112  * The function MSG_mailbox_set_cond set the condition of the mailbox
 113  * specified by the parameter mailbox.
 114  *
 115  * \param mailbox       The mailbox to set the condition.
 116  * \param cond          The new simix condition of the mailbox.
 117  *
 118  */
 119 XBT_PUBLIC(void) MSG_mailbox_set_cond(msg_mailbox_t mailbox, smx_cond_t cond);
 120
 121 /*! \brief MSG_mailbox_get_hostname - get the name of the host owned a mailbox.
 122  *
 123  * The function MSG_mailbox_get_hostname returns name of the host
 124  * owned the mailbox specified by the parameter mailbox.
 125  *
 126  * \param mailbox       The mailbox to get the name of the host.
 127  *
 128  * \return The name of the host owned the mailbox specified by the parameter mailbox.
 129  */
 130 XBT_PUBLIC(const char *) MSG_mailbox_get_hostname(msg_mailbox_t mailbox);
 131
 132 /*! \brief MSG_mailbox_set_hostname - set the name of the host owned a mailbox.
 133  *
 134  * The function MSG_mailbox_set_hostname sets the name of the host
 135  * owned the mailbox specified by the parameter mailbox.
 136  *
 137  * \param mailbox       The mailbox to set the name of the host.
 138  * \param hostname      The name of the owner of the mailbox.
 139  *
 140  */
 141 XBT_PUBLIC(void)
 142 MSG_mailbox_set_hostname(msg_mailbox_t mailbox, const char *hostname);
 143
 144
 145 /*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
 146  *
 147  * The function MSG_mailbox_is_empty tests if a mailbox is empty
 148  * (contains no msg task).
 149  *
 150  * \param mailbox       The mailbox to get test.
 151  *
 152  * \return      The function returns 1 if the mailbox is empty. Otherwise the function
 153  *              returns 0.
 154  */
 155 XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
 156
 157 /*! \brief MSG_mailbox_remove - remove a task from a mailbox.
 158  *
 159  * The MSG_mailbox_remove removes a task from a specified mailbox.
 160  *
 161  * \param mailbox       The mailbox concerned by this operation.
 162  * \param task          The task to remove from the mailbox.
 163  */
 164 XBT_PUBLIC(void) MSG_mailbox_remove(msg_mailbox_t mailbox, m_task_t task);
 165
 166 /*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
 167  *
 168  * The MSG_mailbox_get_head returns the task at the head of the mailbox.
 169  * This function does not remove the task from the mailbox (contrary to
 170  * the function MSG_mailbox_pop_head).
 171  *
 172  * \param mailbox       The mailbox concerned by the operation.
 173  *
 174  * \return              The task at the head of the mailbox.
 175  */
 176 XBT_PUBLIC(m_task_t)
 177   MSG_mailbox_get_head(msg_mailbox_t mailbox);
 178
 179 /*! \brief MSG_mailbox_pop_head - get the task at the head of a mailbox
 180  * and remove it from it.
 181  *
 182  * The MSG_mailbox_pop_head returns the task at the head of the mailbox
 183  * and remove it from it.
 184  *
 185  * \param mailbox       The mailbox concerned by the operation.
 186  *
 187  * \return              The task at the head of the mailbox.
 188  */
 189 XBT_PUBLIC(m_task_t)
 190   MSG_mailbox_pop_head(msg_mailbox_t mailbox);
 191
 192 /*! \brief MSG_mailbox_get_first_host_task - get the first msg task
 193  * of a specified mailbox, sended by a process of a specified host.
 194  *
 195  * \param mailbox       The mailbox concerned by the operation.
 196  * \param host          The msg host of the process that has sended the
 197  *                      task.
 198  *
 199  * \return              The first task in the mailbox specified by the
 200  *                      parameter mailbox and sended by a process located
 201  *                      on the host specified by the parameter host.
 202  */
 203 XBT_PUBLIC(m_task_t)
 204   MSG_mailbox_get_first_host_task(msg_mailbox_t mailbox, m_host_t host);
 205
 206 /*! \brief MSG_mailbox_get_count_host_waiting_tasks - Return the number of tasks
 207    waiting to be received in a mailbox and sent by a host.
 208  *
 209  * \param mailbox       The mailbox concerned by the operation.
 210  * \param host          The msg host containing the processes that have sended the
 211  *                      tasks.
 212  *
 213  * \return              The number of tasks in the mailbox specified by the
 214  *                      parameter mailbox and sended by all the processes located
 215  *                      on the host specified by the parameter host.
 216  */
 217 XBT_PUBLIC(int)
 218 MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
 219                                          m_host_t host);
 220
 221
 222 SG_END_DECL()
 223 #endif /* !SMX_MAILBOX_H */