1 /* Copyright (c) 2008-2015. The SimGrid Team.
2 * All rights reserved. */
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. */
12 #include "simgrid/simix.h"
13 #include "simgrid/msg.h"
17 #define MAX_ALIAS_NAME ((size_t)260)
19 /*! \brief MSG_mailbox_new - create a new mailbox.
21 * The function MSG_mailbox_new creates a new mailbox identified by the key specified
22 * by the parameter alias and add it in the global dictionary.
24 * \param alias The alias of the mailbox to create.
26 * \return The newly created mailbox.
28 XBT_PUBLIC(msg_mailbox_t)
29 MSG_mailbox_new(const char *alias);
31 XBT_PRIVATE void MSG_mailbox_free(void *mailbox);
33 /* \brief MSG_mailbox_free - release a mailbox from the memory.
35 * The function MSG_mailbox_free release a mailbox from the memory but does
36 * not remove it from the dictionary.
38 * \param mailbox The mailbox to release.
40 * \see MSG_mailbox_destroy.
42 XBT_PRIVATE void MSG_mailbox_free(void *mailbox);
44 /* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
46 * The function MSG_mailbox_get_by_alias returns the mailbox associated with
47 * the key specified by the parameter alias. If the mailbox does not exists,
48 * the function create it.
50 * \param alias The alias of the mailbox to return.
52 * \return The mailbox associated with the alias specified as parameter
53 * or a new mailbox if the key does not match.
55 XBT_PUBLIC(msg_mailbox_t)
56 MSG_mailbox_get_by_alias(const char *alias);
58 /*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
60 * The function MSG_mailbox_is_empty tests if a mailbox is empty
61 * (contains no msg task).
63 * \param mailbox The mailbox to get test.
65 * \return The function returns 1 if the mailbox is empty. Otherwise the function
68 XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
70 /* \brief MSG_mailbox_set_async - set a mailbox as eager
72 * The function MSG_mailbox_set_async sets the mailbox to a permanent receiver mode
73 * Messages sent to this mailbox will then be sent just after the send is issued,
74 * without waiting for the corresponding receive.
76 * This call should be done before issuing any receive, and on the receiver's side only
78 * \param alias The alias of the mailbox to modify.
81 XBT_PUBLIC(void) MSG_mailbox_set_async(const char *alias);
83 /*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
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).
89 * \param mailbox The mailbox concerned by the operation.
91 * \return The task at the head of the mailbox.
93 XBT_PUBLIC(msg_task_t)
94 MSG_mailbox_get_head(msg_mailbox_t mailbox);
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.
99 * \param mailbox The mailbox concerned by the operation.
100 * \param host The msg host containing the processes that have sended the
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.
108 MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
111 #ifdef MSG_USE_DEPRECATED
112 /* \brief MSG_mailbox_get_by_channel - get a mailbox of the specified host from its channel.
114 * The function MSG_mailbox_get_by_channel returns the mailbox of the
115 * specified host from the channel specified by the parameter
116 * channel. If the mailbox does not exists, the function fails.
118 * \param host The host containing he mailbox to get.
119 * \param channel The channel used to identify the mailbox.
121 * \return The mailbox of the specified host associated the channel
122 * specified as parameter.
125 XBT_PUBLIC(msg_mailbox_t)
126 MSG_mailbox_get_by_channel(msg_host_t host, m_channel_t channel);
130 #endif /* !MSG_MAILBOX_H */