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