From 5167defc30b99a1651bb02fe7bae4d5ec37cd122 Mon Sep 17 00:00:00 2001 From: navarrop Date: Mon, 13 Sep 2010 16:33:37 +0000 Subject: [PATCH] Update doc for icomms. git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@8182 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- doc/FAQ.doc | 23 +++++++++++---- doc/module-msg.doc | 18 +++++++++++- src/msg/gos.c | 72 +++++++++++++++++++++++++++++++++++++--------- 3 files changed, 93 insertions(+), 20 deletions(-) diff --git a/doc/FAQ.doc b/doc/FAQ.doc index a95cadae00..8641c93441 100644 --- 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 b95959e4d0..a84b763067 100644 --- 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 b0a60c6fd3..d9f7c02287 100644 --- 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