Logo AND Algorithmique Numérique Distribuée

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