X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/0a0481f82fc27b7306940b78c411a3d6e5c84d1c..19a9b26d01348385d94fe24c9e452c5ec427ae20:/src/msg/msg_gos.c

diff --git a/src/msg/msg_gos.c b/src/msg/msg_gos.c
index 5cd5b9020e..5008fd6f92 100644
--- a/src/msg/msg_gos.c
+++ b/src/msg/msg_gos.c
@@ -153,6 +153,14 @@ MSG_parallel_task_create(const char *name, int host_nb,
   return task;
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Executes a parallel task and waits for its termination.
+ *
+ * \param task a #m_task_t to execute on the location on which the agent is running.
+ *
+ * \return #MSG_OK if the task was successfully completed, #MSG_TASK_CANCELED
+ * or #MSG_HOST_FAILURE otherwise
+ */
 MSG_error_t MSG_parallel_task_execute(m_task_t task)
 {
   simdata_task_t simdata = NULL;
@@ -247,6 +255,21 @@ MSG_error_t MSG_process_sleep(double nb_sec)
   }
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Receives a task from a mailbox from a specific host.
+ *
+ * This is a blocking function, the execution flow will be blocked
+ * until the task is received. See #MSG_task_irecv
+ * for receiving tasks asynchronously.
+ *
+ * \param task a memory location for storing a #m_task_t.
+ * \param alias name of the mailbox to receive the task from
+ * \param host a #m_host_t host from where the task was sent
+ *
+ * \return Returns
+ * #MSG_OK if the task was successfully received,
+ * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise.
+ */
 MSG_error_t
 MSG_task_receive_from_host(m_task_t * task, const char *alias,
                            m_host_t host)
@@ -254,11 +277,41 @@ MSG_task_receive_from_host(m_task_t * task, const char *alias,
   return MSG_task_receive_ext(task, alias, -1, host);
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Receives a task from a mailbox.
+ *
+ * This is a blocking function, the execution flow will be blocked
+ * until the task is received. See #MSG_task_irecv
+ * for receiving tasks asynchronously.
+ *
+ * \param task a memory location for storing a #m_task_t.
+ * \param alias name of the mailbox to receive the task from
+ *
+ * \return Returns
+ * #MSG_OK if the task was successfully received,
+ * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise.
+ */
 MSG_error_t MSG_task_receive(m_task_t * task, const char *alias)
 {
   return MSG_task_receive_with_timeout(task, alias, -1);
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Receives a task from a mailbox with a given timeout.
+ *
+ * This is a blocking function with a timeout, the execution flow will be blocked
+ * until the task is received or the timeout is achieved. See #MSG_task_irecv
+ * for receiving tasks asynchronously.  You can provide a -1 timeout
+ * to obtain an infinite timeout.
+ *
+ * \param task a memory location for storing a #m_task_t.
+ * \param alias name of the mailbox to receive the task from
+ * \param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_receive)
+ *
+ * \return Returns
+ * #MSG_OK if the task was successfully received,
+ * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise.
+ */
 MSG_error_t
 MSG_task_receive_with_timeout(m_task_t * task, const char *alias,
                               double timeout)
@@ -266,6 +319,23 @@ MSG_task_receive_with_timeout(m_task_t * task, const char *alias,
   return MSG_task_receive_ext(task, alias, timeout, NULL);
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Receives a task from a mailbox from a specific host with a given timeout.
+ *
+ * This is a blocking function with a timeout, the execution flow will be blocked
+ * until the task is received or the timeout is achieved. See #MSG_task_irecv
+ * for receiving tasks asynchronously. You can provide a -1 timeout
+ * to obtain an infinite timeout.
+ *
+ * \param task a memory location for storing a #m_task_t.
+ * \param alias name of the mailbox to receive the task from
+ * \param timeout is the maximum wait time for completion (provide -1 for no timeout)
+ * \param host a #m_host_t host from where the task was sent
+ *
+ * \return Returns
+ * #MSG_OK if the task was successfully received,
+* #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise.
+ */
 MSG_error_t
 MSG_task_receive_ext(m_task_t * task, const char *alias, double timeout,
                      m_host_t host)
@@ -662,7 +732,7 @@ int MSG_comm_waitany(xbt_dynar_t comms)
  * \ingroup msg_gos_functions
  * \brief Returns the error (if any) that occured during a finished communication.
  * \param comm a finished communication
- * \return the status of the communication, or MSG_OK if no error occured
+ * \return the status of the communication, or #MSG_OK if no error occured
  * during the communication
  */
 MSG_error_t MSG_comm_get_status(msg_comm_t comm) {
@@ -670,6 +740,12 @@ MSG_error_t MSG_comm_get_status(msg_comm_t comm) {
   return comm->status;
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Get a task (#m_task_t) from a communication
+ *
+ * \param comm the communication where to get the task
+ * \return the task from the communication
+ */
 m_task_t MSG_comm_get_task(msg_comm_t comm)
 {
   xbt_assert(comm, "Invalid parameter");
@@ -696,13 +772,39 @@ void MSG_comm_copy_data_from_SIMIX(smx_action_t comm, void* buff, size_t buff_si
   }
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Sends a task to a mailbox
+ *
+ * This is a blocking function, the execution flow will be blocked
+ * until the task is sent (and received in the other side if #MSG_task_receive is used).
+ * See #MSG_task_isend for sending tasks asynchronously.
+ *
+ * \param task the task to be sent
+ * \param alias the mailbox name to where the task is sent
+ *
+ * \return Returns #MSG_OK if the task was successfully sent,
+ * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise.
+ */
 MSG_error_t MSG_task_send(m_task_t task, const char *alias)
 {
   XBT_DEBUG("MSG_task_send: Trying to send a message on mailbox '%s'", alias);
   return MSG_task_send_with_timeout(task, alias, -1);
 }
 
-
+/** \ingroup msg_gos_functions
+ * \brief Sends a task to a mailbox with a maximum rate
+ *
+ * This is a blocking function, the execution flow will be blocked
+ * until the task is sent. The maxrate parameter allows the application
+ * to limit the bandwidth utilization of network links when sending the task.
+ *
+ * \param task the task to be sent
+ * \param alias the mailbox name to where the task is sent
+ * \param maxrate the maximum communication rate for sending this task
+ *
+ * \return Returns #MSG_OK if the task was successfully sent,
+ * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE otherwise.
+ */
 MSG_error_t
 MSG_task_send_bounded(m_task_t task, const char *alias, double maxrate)
 {
@@ -710,7 +812,19 @@ MSG_task_send_bounded(m_task_t task, const char *alias, double maxrate)
   return MSG_task_send(task, alias);
 }
 
-
+/** \ingroup msg_gos_functions
+ * \brief Sends a task to a mailbox with a timeout
+ *
+ * This is a blocking function, the execution flow will be blocked
+ * until the task is sent or the timeout is achieved.
+ *
+ * \param task the task to be sent
+ * \param alias the mailbox name to where the task is sent
+ * \param timeout is the maximum wait time for completion (if -1, this call is the same as #MSG_task_send)
+ *
+ * \return Returns #MSG_OK if the task was successfully sent,
+ * #MSG_HOST_FAILURE, or #MSG_TRANSFER_FAILURE, or #MSG_TIMEOUT otherwise.
+ */
 MSG_error_t
 MSG_task_send_with_timeout(m_task_t task, const char *alias,
                            double timeout)
@@ -719,6 +833,12 @@ MSG_task_send_with_timeout(m_task_t task, const char *alias,
                                       task, timeout);
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Look if there is a communication on a mailbox
+ *
+ * \param alias the mailbox to listen
+ * \return return 1 if there is a communication or 0
+ */
 int MSG_task_listen(const char *alias)
 {
   CHECK_HOST();
@@ -726,6 +846,14 @@ int MSG_task_listen(const char *alias)
   return !MSG_mailbox_is_empty(MSG_mailbox_get_by_alias(alias));
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Look if there is a communication on a mailbox from
+ * a given host
+ *
+ * \param alias the mailbox to listen
+ * \param host the host to check for communication
+ * \return return 1 if there is a communication or 0
+ */
 int MSG_task_listen_from_host(const char *alias, m_host_t host)
 {
   CHECK_HOST();
@@ -735,6 +863,13 @@ int MSG_task_listen_from_host(const char *alias, m_host_t host)
                                                (alias), host);
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Look if there is a communication on a mailbox and return the
+ * PID from sender process
+ *
+ * \param alias the mailbox to listen
+ * \return return the PID of process(or 0 in case of problem)
+ */
 int MSG_task_listen_from(const char *alias)
 {
   m_task_t task;
@@ -994,11 +1129,6 @@ MSG_task_get_with_timeout(m_task_t * task, m_channel_t channel,
   return MSG_task_get_ext(task, channel, max_duration, NULL);
 }
 
-/** \defgroup msg_gos_functions MSG Operating System Functions
- *  \brief This section describes the functions that can be used
- *  by an agent for handling some task.
- */
-
 MSG_error_t
 MSG_task_get_ext(m_task_t * task, m_channel_t channel, double timeout,
                  m_host_t host)