src/msg/mailbox.h

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