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