Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Fix lua platform script
[simgrid.git] / src / msg / msg_mailbox.h
1 /* Copyright (c) 2008, 2009, 2010. The SimGrid Team.
2  * All rights reserved.                                                     */
3
4 /* This program is free software; you can redistribute it and/or modify it
5   * under the terms of the license (GNU LGPL) which comes with this package. */
6
7 #ifndef MSG_MAILBOX_H
8 #define MSG_MAILBOX_H
9
10 #include "xbt/fifo.h"
11 #include "simgrid/simix.h"
12 #include "msg/datatypes.h"
13
14
15 SG_BEGIN_DECL()
16 #define MAX_ALIAS_NAME  ((size_t)260)
17
18 /*! \brief MSG_mailbox_new - create a new mailbox.
19  *
20  * The function MSG_mailbox_new creates a new mailbox identified by the key specified
21  * by the parameter alias and add it in the global dictionary.
22  *
23  * \param alias    The alias of the mailbox to create.
24  *
25  * \return    The newly created mailbox.
26  */
27 XBT_PUBLIC(msg_mailbox_t)
28     MSG_mailbox_new(const char *alias);
29
30 void MSG_mailbox_free(void *mailbox);
31
32 /* \brief MSG_mailbox_free - release a mailbox from the memory.
33  *
34  * The function MSG_mailbox_free release a mailbox from the memory but does
35  * not remove it from the dictionary.
36  *
37  * \param mailbox  The mailbox to release.
38  *
39  * \see      MSG_mailbox_destroy.
40  */
41 void MSG_mailbox_free(void *mailbox);
42
43 /* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
44  *
45  * The function MSG_mailbox_get_by_alias returns the mailbox associated with
46  * the key specified by the parameter alias. If the mailbox does not exists,
47  * the function create it.
48  *
49  * \param alias    The alias of the mailbox to return.
50  *
51  * \return  The mailbox associated with the alias specified as parameter
52  *    or a new mailbox if the key does not match.
53  */
54 XBT_PUBLIC(msg_mailbox_t)
55     MSG_mailbox_get_by_alias(const char *alias);
56
57 /*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
58  *
59  * The function MSG_mailbox_is_empty tests if a mailbox is empty
60  * (contains no msg task).
61  *
62  * \param mailbox  The mailbox to get test.
63  *
64  * \return  The function returns 1 if the mailbox is empty. Otherwise the function
65  *    returns 0.
66  */
67 XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
68
69 /* \brief MSG_mailbox_set_async - set a mailbox as eager
70  *
71  * The function MSG_mailbox_set_async sets the mailbox to a permanent receiver mode
72  * Messages sent to this mailbox will then be sent just after the send is issued,
73  * without waiting for the corresponding receive.
74  *
75  * This call should be done before issuing any receive, and on the receiver's side only
76  *
77  * \param alias    The alias of the mailbox to modify.
78  *
79  */
80 void MSG_mailbox_set_async(const char *alias);
81
82 /*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
83  *
84  * The MSG_mailbox_get_head returns the task at the head of the mailbox.
85  * This function does not remove the task from the mailbox (contrary to
86  * the function MSG_mailbox_pop_head).
87  *
88  * \param mailbox  The mailbox concerned by the operation.
89  *
90  * \return    The task at the head of the mailbox.
91  */
92 XBT_PUBLIC(msg_task_t)
93     MSG_mailbox_get_head(msg_mailbox_t mailbox);
94
95 /*! \brief MSG_mailbox_get_count_host_waiting_tasks - Return the number of tasks
96    waiting to be received in a mailbox and sent by a host.
97  *
98  * \param mailbox  The mailbox concerned by the operation.
99  * \param host    The msg host containing the processes that have sended the
100  *      tasks.
101  *
102  * \return    The number of tasks in the mailbox specified by the
103  *      parameter mailbox and sended by all the processes located
104  *      on the host specified by the parameter host.
105  */
106 XBT_PUBLIC(int)
107 MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
108                                          msg_host_t host);
109
110 #ifdef MSG_USE_DEPRECATED
111 /* \brief MSG_mailbox_get_by_channel - get a mailbox of the specified host from its channel.
112  *
113  * The function MSG_mailbox_get_by_channel returns the mailbox of the
114  * specified host from the channel specified by the parameter
115  * channel. If the mailbox does not exists, the function fails.
116  *
117  * \param host      The host containing he mailbox to get.
118  * \param channel   The channel used to identify the mailbox.
119  *
120  * \return The mailbox of the specified host associated the channel
121  *         specified as parameter.
122  *
123  */
124 XBT_PUBLIC(msg_mailbox_t)
125     MSG_mailbox_get_by_channel(msg_host_t host, m_channel_t channel);
126 #endif
127
128 SG_END_DECL()
129 #endif                          /* !MSG_MAILBOX_H */