Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
fix for windows -- not sure if it's still mandatory, but I guess so
[simgrid.git] / src / msg / msg_mailbox.h
index 94e0c2a..f587002 100644 (file)
-#ifndef SMX_MAILBOX_H\r
-#define SMX_MAILBOX_H\r
-\r
-#include "xbt/fifo.h"\r
-#include "simix/private.h"\r
-#include "msg/datatypes.h"\r
-\r
-#ifdef __cplusplus\r
-extern "C" {\r
-#endif\r
-\r
-#define MAX_ALIAS_NAME ((size_t)260)\r
-\r
-/* this structure represents a mailbox */\r
-typedef struct s_msg_mailbox\r
-{\r
-       char* alias;                    /* the key of the mailbox in the dictionary                             */\r
-       xbt_fifo_t tasks;               /* the list of the tasks in the mailbox                                 */\r
-       smx_cond_t cond;                /* the condition on the mailbox                                                 */\r
-       char* hostname;                 /* the name of the host containing the mailbox                  */\r
-}s_msg_mailbox_t, * msg_mailbox_t;\r
-\r
-/*\r
- * Initialization of the mailbox module.\r
- */\r
-void\r
-MSG_mailbox_mod_init(void);\r
-\r
-/*\r
- * Terminaison of the mailbox module.\r
- */\r
-void\r
-MSG_mailbox_mod_exit(void);\r
-\r
-/*! \brief MSG_get_mailboxes - get the dictionary containing all the mailboxes.\r
- * \r
- * The function MSG_get_mailboxes returns the dictionary containing all the mailboxes\r
- * of the simulation. A mailbox allow different processes to communicate using msg tasks.\r
- * It is identified by an alias which is a key of the dictionary containing all of them.\r
- * \r
- * \return     The dictionary containing all the mailboxes of the simulation.\r
- */\r
-xbt_dict_t\r
-MSG_get_mailboxes(void);\r
-\r
-/*! \brief MSG_mailbox_new - create a new mailbox.\r
- *\r
- * The function MSG_mailbox_new creates a new mailbox identified by the key specified\r
- * by the parameter alias.\r
- *\r
- * \param alias                The alias of the mailbox to create.\r
- * \r
- * \return                     The newly created mailbox.\r
- */\r
-msg_mailbox_t\r
-MSG_mailbox_new(const char *alias);\r
-\r
-/* \brief MSG_mailbox_destroy - destroy a mailbox.\r
- *\r
- * The function MSG_mailbox_destroy removes a mailbox from the dictionary containing\r
- * all the mailbox of the simulation an release it from the memory. This function is\r
- * different to the MSG_mailbox_free which only release a mailbox from the memory but\r
- does not remove it from the dictionary.\r
- *\r
- * \param mailbox      The mailbox to destroy.\r
- *\r
- * \see                                MSG_mailbox_free.\r
- */\r
-void\r
-MSG_mailbox_destroy(msg_mailbox_t* mailbox);\r
-\r
-/* \brief MSG_mailbox_free - release a mailbox from the memory.\r
- *\r
- * The function MSG_mailbox_free release a mailbox from the memory but does\r
- * not remove it from the dictionary.\r
- *\r
- * \param mailbox      The mailbox to release.\r
- *\r
- * \see                                MSG_mailbox_destroy.\r
- */\r
-void\r
-MSG_mailbox_free(void* mailbox);\r
-\r
-/* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.\r
- *\r
- * The function MSG_mailbox_get_by_alias returns the mailbox associated with\r
- * the key specified by the parameter alias. If the mailbox does not exists,\r
- * the function create it.\r
- *\r
- * \param alias                The alias of the mailbox to return.\r
- *\r
- * \return                     The mailbox associated with the alias specified as parameter\r
- *                                     or a new mailbox if the key does not match.\r
- */\r
-msg_mailbox_t\r
-MSG_mailbox_get_by_alias(const char* alias);\r
-\r
-/*! \brief MSG_mailbox_get_alias - get the alias associated with the mailbox.\r
- *\r
- * The function MSG_mailbox_get_alias returns the alias of the mailbox specified\r
- * by the parameter mailbox.\r
- *\r
- * \param mailbox      The mailbox to get the alias.\r
- *\r
- * \return                     The alias of the mailbox specified by the parameter mailbox.\r
- */\r
-const char*\r
-MSG_mailbox_get_alias(msg_mailbox_t mailbox);\r
-\r
-/*! \brief MSG_mailbox_get_cond - get the simix condition of a mailbox.\r
- *\r
- * The function MSG_mailbox_get_cond returns the condition of the mailbox specified\r
- * by the parameter mailbox.\r
- *\r
- * \param mailbox      The mailbox to get the condition.\r
- *\r
- * \return                     The simix condition of the mailbox specified by the parameter mailbox.\r
- */\r
-smx_cond_t\r
-MSG_mailbox_get_cond(msg_mailbox_t mailbox);\r
-\r
-/*! \brief MSG_mailbox_set_cond - set the simix condition of a mailbox.\r
- *\r
- * The function MSG_mailbox_set_cond set the condition of the mailbox specified\r
- * by the parameter mailbox.\r
- *\r
- * \param mailbox      The mailbox to set the condition.\r
- * \param cond         The new simix condition of the mailbox.\r
- *\r
- */\r
-void\r
-MSG_mailbox_set_cond(msg_mailbox_t mailbox, smx_cond_t cond);\r
-\r
-/*! \brief MSG_mailbox_get_hostname - get the name of the host owned a mailbox.\r
- *\r
- * The function MSG_mailbox_get_hostname returns name of the host owned the mailbox specified\r
- * by the parameter mailbox.\r
- *\r
- * \param mailbox      The mailbox to get the name of the host.\r
- *\r
- * \return                     The name of the host owned the mailbox specified by the parameter mailbox.\r
- */\r
-const char*\r
-MSG_mailbox_get_hostname(msg_mailbox_t mailbox);\r
-\r
-/*! \brief MSG_mailbox_set_hostname - set the name of the host owned a mailbox.\r
- *\r
- * The function MSG_mailbox_set_hostname sets the name of the host owned the mailbox specified\r
- * by the parameter mailbox.\r
- *\r
- * \param mailbox      The mailbox to set the name of the host.\r
- * \param hostname     The name of the owner of the mailbox.\r
- *\r
- */\r
-void\r
-MSG_mailbox_set_hostname(msg_mailbox_t mailbox, const char* hostname);\r
-\r
-\r
-/*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.\r
- *\r
- * The function MSG_mailbox_is_empty tests if a mailbox is empty (contains no msg task). \r
- *\r
- * \param mailbox      The mailbox to get test.\r
- *\r
- * \return                     The function returns 1 if the mailbox is empty. Otherwise the function\r
- *                                     returns 0.\r
- */\r
-int\r
-MSG_mailbox_is_empty(msg_mailbox_t mailbox);\r
-\r
-/*! \brief MSG_mailbox_put - put a task in a mailbox.\r
- *\r
- * The MSG_mailbox_put puts a task in a specified mailbox.\r
- *\r
- * \param mailbox      The mailbox where put the task.\r
- * \param task         The task to put in the mailbox.\r
- */\r
-void\r
-MSG_mailbox_put(msg_mailbox_t mailbox, m_task_t task);\r
-\r
-/*! \brief MSG_mailbox_remove - remove a task from a mailbox.\r
- *\r
- * The MSG_mailbox_remove removes a task from a specified mailbox.\r
- *\r
- * \param mailbox      The mailbox concerned by this operation.\r
- * \param task         The task to remove from the mailbox.\r
- */\r
-void\r
-MSG_mailbox_remove(msg_mailbox_t mailbox, m_task_t task);\r
-\r
-/*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.\r
- *\r
- * The MSG_mailbox_get_head returns the task at the head of the mailbox.\r
- * This function does not remove the task from the mailbox (contrary to\r
- * the function MSG_mailbox_pop_head).\r
- *\r
- * \param mailbox      The mailbox concerned by the operation.\r
- *\r
- * \return                     The task at the head of the mailbox.\r
- */\r
-m_task_t\r
-MSG_mailbox_get_head(msg_mailbox_t mailbox);\r
-\r
-/*! \brief MSG_mailbox_pop_head - get the task at the head of a mailbox\r
- * and remove it from it.\r
- *\r
- * The MSG_mailbox_pop_head returns the task at the head of the mailbox\r
- * and remove it from it.\r
- *\r
- * \param mailbox      The mailbox concerned by the operation.\r
- *\r
- * \return                     The task at the head of the mailbox.\r
- */\r
-m_task_t\r
-MSG_mailbox_pop_head(msg_mailbox_t mailbox);\r
-\r
-/*! \brief MSG_mailbox_get_first_host_task - get the first msg task\r
- * of a specified mailbox, sended by a process of a specified host.\r
- *\r
- * \param mailbox      The mailbox concerned by the operation.\r
- * \param host         The msg host of the process that has sended the\r
- *                                     task.\r
- *\r
- * \return                     The first task in the mailbox specified by the\r
- *                                     parameter mailbox and sended by a process located\r
- *                                     on the host specified by the parameter host.\r
- */\r
-m_task_t\r
-MSG_mailbox_get_first_host_task(msg_mailbox_t mailbox, m_host_t host);\r
-\r
-/*! \brief MSG_mailbox_get_count_host_tasks - get the number of msg tasks\r
- * of a specified mailbox, sended by all the process of a specified host.\r
- *\r
- * \param mailbox      The mailbox concerned by the operation.\r
- * \param host         The msg host containing the processes that have sended the\r
- *                                     tasks.\r
- *\r
- * \return                     The number of tasks in the mailbox specified by the\r
- *                                     parameter mailbox and sended by all the processes located\r
- *                                     on the host specified by the parameter host.\r
- */\r
-int\r
-MSG_mailbox_get_count_host_tasks(msg_mailbox_t mailbox, m_host_t host);\r
-\r
-\r
-#ifdef __cplusplus\r
-}\r
-#endif\r
-\r
-#endif /* !SMX_MAILBOX_H */\r
-\r
+/* Copyright (c) 2008, 2009, 2010. The SimGrid Team.
+ * All rights reserved.                                                     */
+
+/* This program is free software; you can redistribute it and/or modify it
+  * under the terms of the license (GNU LGPL) which comes with this package. */
+
+#ifndef MSG_MAILBOX_H
+#define MSG_MAILBOX_H
+
+#include "xbt/fifo.h"
+#include "simgrid/simix.h"
+#include "msg/datatypes.h"
+
+
+SG_BEGIN_DECL()
+#define MAX_ALIAS_NAME  ((size_t)260)
+
+/*! \brief MSG_mailbox_new - create a new mailbox.
+ *
+ * The function MSG_mailbox_new creates a new mailbox identified by the key specified
+ * by the parameter alias and add it in the global dictionary.
+ *
+ * \param alias    The alias of the mailbox to create.
+ *
+ * \return    The newly created mailbox.
+ */
+XBT_PUBLIC(msg_mailbox_t)
+    MSG_mailbox_new(const char *alias);
+
+void MSG_mailbox_free(void *mailbox);
+
+/* \brief MSG_mailbox_free - release a mailbox from the memory.
+ *
+ * The function MSG_mailbox_free release a mailbox from the memory but does
+ * not remove it from the dictionary.
+ *
+ * \param mailbox  The mailbox to release.
+ *
+ * \see      MSG_mailbox_destroy.
+ */
+void MSG_mailbox_free(void *mailbox);
+
+/* \brief MSG_mailbox_get_by_alias - get a mailbox from its alias.
+ *
+ * The function MSG_mailbox_get_by_alias returns the mailbox associated with
+ * the key specified by the parameter alias. If the mailbox does not exists,
+ * the function create it.
+ *
+ * \param alias    The alias of the mailbox to return.
+ *
+ * \return  The mailbox associated with the alias specified as parameter
+ *    or a new mailbox if the key does not match.
+ */
+XBT_PUBLIC(msg_mailbox_t)
+    MSG_mailbox_get_by_alias(const char *alias);
+
+/*! \brief MSG_mailbox_is_empty - test if a mailbox is empty.
+ *
+ * The function MSG_mailbox_is_empty tests if a mailbox is empty
+ * (contains no msg task).
+ *
+ * \param mailbox  The mailbox to get test.
+ *
+ * \return  The function returns 1 if the mailbox is empty. Otherwise the function
+ *    returns 0.
+ */
+XBT_PUBLIC(int) MSG_mailbox_is_empty(msg_mailbox_t mailbox);
+
+/* \brief MSG_mailbox_set_async - set a mailbox as eager
+ *
+ * The function MSG_mailbox_set_async sets the mailbox to a permanent receiver mode
+ * Messages sent to this mailbox will then be sent just after the send is issued,
+ * without waiting for the corresponding receive.
+ *
+ * This call should be done before issuing any receive, and on the receiver's side only
+ *
+ * \param alias    The alias of the mailbox to modify.
+ *
+ */
+XBT_PUBLIC(void) MSG_mailbox_set_async(const char *alias);
+
+/*! \brief MSG_mailbox_get_head - get the task at the head of a mailbox.
+ *
+ * The MSG_mailbox_get_head returns the task at the head of the mailbox.
+ * This function does not remove the task from the mailbox (contrary to
+ * the function MSG_mailbox_pop_head).
+ *
+ * \param mailbox  The mailbox concerned by the operation.
+ *
+ * \return    The task at the head of the mailbox.
+ */
+XBT_PUBLIC(msg_task_t)
+    MSG_mailbox_get_head(msg_mailbox_t mailbox);
+
+/*! \brief MSG_mailbox_get_count_host_waiting_tasks - Return the number of tasks
+   waiting to be received in a mailbox and sent by a host.
+ *
+ * \param mailbox  The mailbox concerned by the operation.
+ * \param host    The msg host containing the processes that have sended the
+ *      tasks.
+ *
+ * \return    The number of tasks in the mailbox specified by the
+ *      parameter mailbox and sended by all the processes located
+ *      on the host specified by the parameter host.
+ */
+XBT_PUBLIC(int)
+MSG_mailbox_get_count_host_waiting_tasks(msg_mailbox_t mailbox,
+                                         msg_host_t host);
+
+#ifdef MSG_USE_DEPRECATED
+/* \brief MSG_mailbox_get_by_channel - get a mailbox of the specified host from its channel.
+ *
+ * The function MSG_mailbox_get_by_channel returns the mailbox of the
+ * specified host from the channel specified by the parameter
+ * channel. If the mailbox does not exists, the function fails.
+ *
+ * \param host      The host containing he mailbox to get.
+ * \param channel   The channel used to identify the mailbox.
+ *
+ * \return The mailbox of the specified host associated the channel
+ *         specified as parameter.
+ *
+ */
+XBT_PUBLIC(msg_mailbox_t)
+    MSG_mailbox_get_by_channel(msg_host_t host, m_channel_t channel);
+#endif
+
+SG_END_DECL()
+#endif                          /* !MSG_MAILBOX_H */