src/msg/mailbox.h

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