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