Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
merge conflicts
[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 SMX_MAILBOX_H
8 #define SMX_MAILBOX_H
9
10 #include "xbt/fifo.h"
11 #include "simix/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 /* \brief MSG_mailbox_free - release a mailbox from the memory.
31  *
32  * The function MSG_mailbox_free release a mailbox from the memory but does
33  * not remove it from the dictionary.
34  *
35  * \param mailbox       The mailbox to release.
36  *
37  * \see                 MSG_mailbox_destroy.
38  */
39 void MSG_mailbox_free(void *mailbox);
40
41 /* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
42  *
43  * The function MSG_mailbox_get_by_alias returns the mailbox associated with
44  * the key specified by the parameter alias. If the mailbox does not exists,
45  * the function create it.
46  *
47  * \param alias         The alias of the mailbox to return.
48  *
49  * \return      The mailbox associated with the alias specified as parameter
50  *              or a new mailbox if the key does not match.
51  */
52 XBT_PUBLIC(msg_mailbox_t)
53     MSG_mailbox_get_by_alias(const char *alias);
54
55 /* \brief MSG_mailbox_get_by_channel - get a mailbox of the specified host from its channel.
56  *
57  * The function MSG_mailbox_get_by_channel returns the mailbox of the
58  * specified host from the channel specified by the parameter
59  * channel. If the mailbox does not exists, the function fails.
60  *
61  * \param host          The host containing he mailbox to get.
62  * \param channel       The channel used to identify the mailbox.
63  *
64  * \return The mailbox of the specified host associated the channel
65  *         specified as parameter.
66  *
67  */
68 XBT_PUBLIC(msg_mailbox_t)
69     MSG_mailbox_get_by_channel(m_host_t host, m_channel_t channel);
70
71 /*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
72  *
73  * The function MSG_mailbox_is_empty tests if a mailbox is empty
74  * (contains no msg task).
75  *
76  * \param mailbox       The mailbox to get test.
77  *
78  * \return      The function returns 1 if the mailbox is empty. Otherwise the function
79  *              returns 0.
80  */
81 XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
82
83 /*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
84  *
85  * The MSG_mailbox_get_head returns the task at the head of the mailbox.
86  * This function does not remove the task from the mailbox (contrary to
87  * the function MSG_mailbox_pop_head).
88  *
89  * \param mailbox       The mailbox concerned by the operation.
90  *
91  * \return              The task at the head of the mailbox.
92  */
93 XBT_PUBLIC(m_task_t)
94     MSG_mailbox_get_head(msg_mailbox_t mailbox);
95
96 /*! \brief MSG_mailbox_get_count_host_waiting_tasks - Return the number of tasks
97    waiting to be received in a mailbox and sent by a host.
98  *
99  * \param mailbox       The mailbox concerned by the operation.
100  * \param host          The msg host containing the processes that have sended the
101  *                      tasks.
102  *
103  * \return              The number of tasks in the mailbox specified by the
104  *                      parameter mailbox and sended by all the processes located
105  *                      on the host specified by the parameter host.
106  */
107 XBT_PUBLIC(int)
108 MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
109                                          m_host_t host);
110
111
112 SG_END_DECL()
113 #endif                          /* !SMX_MAILBOX_H */