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