Update doc for icomms.

git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@8182 48e7efb5-ca39-0410-a469-dd3cf9ba447f

diff --git a/doc/FAQ.doc b/doc/FAQ.doc
index a95cada..8641c93 100644 (file)
--- a/doc/FAQ.doc
+++ b/doc/FAQ.doc
@@ -1068,12 +1068,23 @@ you still don't see how to do it, please come back to us...
 
 \subsubsection faq_MIA_asynchronous I want to do asynchronous communications in MSG
 
-Up until now, there is no asynchronous communications in MSG. However,
-you can create as many process as you want so you should be able to do
-whatever you want... I've written a queue module to help implementing
-some asynchronous communications at low cost (creating thousands of
-process only to handle communications may be problematic in term of
-performance at some point). I'll add it in the distribution asap.
+We can now use asynchronous communication in MSG by using function :
+
+       MSG_task_isend()
+       
+       MSG_task_irecv()
+       
+       MSG_comm_test()
+       
+       MSG_comm_wait()
+       
+       MSG_comm_waitall()
+       
+       MSG_comm_waitany()
+       
+       MSG_comm_destroy()
+       
+See page :\ref MSG_ex_asynchronous_communications
 
 \subsubsection faq_MIA_thread_synchronization I need to synchronize my MSG processes
 

diff --git a/doc/module-msg.doc b/doc/module-msg.doc
index b95959e..a84b763 100644 (file)
--- a/doc/module-msg.doc
+++ b/doc/module-msg.doc
@@ -201,13 +201,29 @@
 
     \dontinclude msg/icomms/peer2.c
 
-    \section MSG_ext_icomms_fct Waitall function for sender
+    \section MSG_ext_icomms_fct_Waitall Waitall function for sender
 
     The use of this function permit to send all messages and wait for the completion of all in one time.
 
     \skipline Sender function
     \until end_of_sender
 
+    \section MSG_ext_icomms_fct_Waitany Waitany function
+
+    The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table.
+
+    \subsection MSG_ext_icomms_fct_Waitany_sender From a sender
+       We can use this function to wait all sended messages.
+    \dontinclude msg/icomms/peer3.c
+    \skipline Sender function
+    \until end_of_sender
+
+    \subsection MSG_ext_icomms_fct_Waitany_receiver From a receiver
+       We can also wait for the receiving of all messages.
+    \dontinclude msg/icomms/peer3.c
+    \skipline Receiver function
+    \until end_of_receiver
+
 */
 
 /** \page MSG_ex_master_slave_scrip_lua Master/slave application using lua console

diff --git a/src/msg/gos.c b/src/msg/gos.c
index b0a60c6..d9f7c02 100644 (file)
--- a/src/msg/gos.c
+++ b/src/msg/gos.c
@@ -410,6 +410,16 @@ MSG_task_receive_ext(m_task_t * task, const char *alias, double timeout,
                        timeout);
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Send a task on a channel.
+ *
+ * This function takes two parameter.
+ * \param task a #m_task_t to send on another location.
+ * \param alias the channel on which the agent should put this
+ task. This value has to be >=0 and < than the maximal number of
+ channels fixed with MSG_set_channel_number().
+ * \return the msg_comm_t communication.
+ */
 msg_comm_t MSG_task_isend(m_task_t task, const char *alias) {
        simdata_task_t t_simdata = NULL;
        m_process_t process = MSG_process_self();
@@ -441,6 +451,16 @@ msg_comm_t MSG_task_isend(m_task_t task, const char *alias) {
                        task, sizeof(void*), &t_simdata->comm);
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Listen on a channel for receiving a task from an asynchronous communication.
+ *
+ * It takes two parameters.
+ * \param task a memory location for storing a #m_task_t.
+ * \param alias the channel on which the agent should be
+ listening. This value has to be >=0 and < than the maximal
+ number of channels fixed with MSG_set_channel_number().
+ * \return the msg_comm_t communication.
+ */
 msg_comm_t MSG_task_irecv(m_task_t * task, const char *alias) {
        smx_comm_t comm;
        smx_rdv_t rdv = MSG_mailbox_get_by_alias(alias)->rdv;
@@ -467,12 +487,25 @@ msg_comm_t MSG_task_irecv(m_task_t * task, const char *alias) {
        /* Try to receive it by calling SIMIX network layer */
        return SIMIX_network_irecv(rdv, task, &size);
 }
-
+/** \ingroup msg_gos_functions
+ * \brief Test the status of a communication.
+ *
+ * It takes one parameter.
+ * \param comm the communication to test.
+ * \return the status of the communication:
+ *             TRUE : the communication is completed
+ *             FALSE: the communication is incompleted
+ * If the status is FALSE, don't forget to use MSG_process_sleep() after the test.
+ */
 int MSG_comm_test(msg_comm_t comm) {
        return SIMIX_network_test(comm);
 }
-
-/* After received TRUE to MSG_comm_test() function we have to destroy the communication */
+/** \ingroup msg_gos_functions
+ * \brief After received TRUE to MSG_comm_test(), the communication must be destroyed.
+ *
+ * It takes one parameter.
+ * \param comm the communication to destroy.
+ */
 void MSG_comm_destroy(msg_comm_t comm) {
        if(!(comm->src_proc == SIMIX_process_self()))
        {
@@ -483,6 +516,14 @@ void MSG_comm_destroy(msg_comm_t comm) {
        SIMIX_communication_destroy(comm);
 }
 
+/** \ingroup msg_gos_functions
+ * \brief Wait for the completion of a communication.
+ *
+ * It takes two parameters.
+ * \param comm the communication to wait.
+ * \param timeout Wait until the communication terminates or the timeout occurs
+ * \return MSG_error_t
+ */
 MSG_error_t MSG_comm_wait(msg_comm_t comm, double timeout) {
        xbt_ex_t e;
        MSG_error_t res = MSG_OK;
@@ -516,15 +557,14 @@ MSG_error_t MSG_comm_wait(msg_comm_t comm, double timeout) {
        return res;
 }
 
-
-/* This function is called by a sender and permit to wait for each communication
- *
- * Param:
- * - msg_comm_t *comm a vector of communication
- * - int nb_elem is th esize of the comm vector
- * - timeout for each call of  MSG_comm_wait
- */
-
+/** \ingroup msg_gos_functions
+* \brief This function is called by a sender and permit to wait for each communication
+*
+* It takes three parameters.
+* \param comm a vector of communication
+* \param nb_elem is the size of the comm vector
+* \param timeout for each call of  MSG_comm_wait
+*/
 void MSG_comm_waitall(msg_comm_t *comm,int nb_elem, double timeout) {
        int i=0;
        for(i=0; i<nb_elem; i++)
@@ -532,7 +572,13 @@ void MSG_comm_waitall(msg_comm_t *comm,int nb_elem, double timeout) {
                MSG_comm_wait(comm[i],timeout);
        }
 }
-
+/** \ingroup msg_gos_functions
+* \brief This function wait for the first completed communication
+*
+* It takes on parameter.
+* \param comms a vector of communication
+* \return the position of the completed communication from the xbt_dynar_t.
+*/
 int MSG_comm_waitany(xbt_dynar_t comms) {
        return SIMIX_network_waitany(comms);
 }