X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/a58332db69cf880d47d18e1751a72e8cdc162f31..7fab3edd9dabf63ddf1cea93113158e5a3e2936c:/doc/module-msg.doc diff --git a/doc/module-msg.doc b/doc/module-msg.doc index 7c7eec6508..3df79feacb 100644 --- a/doc/module-msg.doc +++ b/doc/module-msg.doc @@ -1,34 +1,5 @@ -/** \defgroup MSG_JAVA jMSG - \ingroup MSG_API - \brief Java bindings to MSG (\ref MSG_API) - - \htmlonly \endhtmlonly - - MSG was the first distributed programming environment provided within - SimGrid. While almost realistic, it remains quite simple (simplistic?). - This describes the Java bindings to this interface. +/** \addtogroup MSG_API - \section jMSG_who Who should use this (and who shouldn't) - - You should use MSG if you want to study some heuristics for a - given problem you don't really want to implement. If you want to - use the Java programming language, your are in the right - section. To use the C interface, please refer to \ref MSG_C. -*/ - -/** \defgroup MSG_C MSG native - \ingroup MSG_API - \brief Native interface to MSG (\ref MSG_API) - - \htmlonly \endhtmlonly - MSG was the first distributed programming environment provided within SimGrid. While almost realistic, it remains quite simple (simplistic?). This describes the native to MSG. @@ -38,377 +9,382 @@ You should use MSG if you want to study some heuristics for a given problem you don't really want to implement. If you want to use the C programming language, your are in the right - section. To use the Java programming interface, please refer to - \ref MSG_JAVA. -*/ + section. To use the Java or Ruby programming interfaces, please refer to + the documentation provided in the relevant packages. + + \section MSG_funct Offered functionnalities + - \ref msg_simulation + - \ref m_process_management + - \ref m_host_management + - \ref m_task_management + - \ref msg_file_management + - \ref msg_task_usage + - \ref msg_trace_driven + - \ref msg_deprecated_functions + + Also make sure to visit the page @ref MSG_examples. +*/ /** +@defgroup MSG_examples MSG Examples +@ingroup MSG_API + +@htmlonly @endhtmlonly -\defgroup MSG_LUA lMSG - \ingroup MSG_API - \brief Lua bindings to MSG (\ref MSG_API) +MSG comes with an extensive set of examples. It is sometimes difficult +to find the one you need. This list aims at helping you finding the +example from which you can learn what you want to. - \htmlonly \endhtmlonly - - MSG was the first distributed programming environment provided within - SimGrid. While almost realistic, it remains quite simple (simplistic?). - This describes the Lua bindings to this interface. - - \section lMSG_who Who should use this (and who shouldn't) - - You should use MSG if you want to study some heuristics for a - given problem you don't really want to implement. If you want to - use the Lua script language, your are in the right - section. To use the C interface, please refer to \ref MSG_C. +@section MSG_ex_basics Basic examples and features */ -/** @addtogroup MSG_C +/** +@defgroup msg_simulation Main MSG simulation Functions +@ingroup MSG_API +@brief Describes how to setup and control your simulation. + +The basic workflow is the following (check the \ref MSG_examples for +details). + + -# Initialize the library with #MSG_global_init + -# Create a platform (usually by parsing a file with + #MSG_create_environment) + -# Register the functions that your processes are supposed to run with + #MSG_function_register (and maybe #MSG_function_register_default) + -# Launch your processes from a deployment file with #MSG_launch_application + -# Run the simulation with #MSG_main + -# Cleanup the library with #MSG_clean before ending your program + (optional). + +@htmlonly @endhtmlonly +*/ - \section MSG_funct Offered functionnalities - - \ref m_process_management - - \ref m_datatypes_management - - \ref m_host_management - - \ref m_task_management - - \ref msg_gos_functions - - \ref m_channel_management - - \ref msg_easier_life - - \ref msg_simulation +/** @defgroup m_process_management Process Management Functions + * @ingroup MSG_API + * @brief This section describes the process structure of MSG + * (#m_process_t) and the functions for managing it. + */ + +/** @defgroup m_host_management Host Management Functions + * @ingroup MSG_API + * @brief This section describes the host structure of MSG + */ + +/** @defgroup m_task_management Task Management Functions + * @ingroup MSG_API + * @brief This section describes the task structure of MSG + * (#m_task_t) and the functions for managing it. See + * \ref msg_task_usage to see how to put the tasks in action. + * + * \htmlonly \endhtmlonly + */ + +/** @defgroup msg_task_usage Task Actions + * @ingroup MSG_API + * @brief This section describes the functions that can be used + * by a process to execute, communicate or otherwise handle some task. + */ + +/** @defgroup msg_file_management File Management Functions + * @ingroup MSG_API + * @brief This section describes the file structure of MSG + * (#msg_file_t) and the functions for managing it. It + * is based on POSIX functions. + */ + + +/** +@defgroup msg_trace_driven Trace-driven simulations +@ingroup MSG_API +@brief This section describes the functions allowing to build trace-driven simulations. + +\htmlonly \endhtmlonly + +This is very handy when you want to test an algorithm or protocol that +does nothing unless it receives some events from outside. For example, +a P2P protocol reacts to requests from the user, but does nothing if +there is no such event. + +In such situations, SimGrid allows to write your protocol in your C +file, and the events to react to in a separate text file. Declare a +function handling each of the events that you want to accept in your +trace files, register them using #MSG_action_register in your main, +and then use #MSG_action_trace_run to launch the simulation. You can +either have one trace file containing all your events, or a file per +simulated process. + +Check the examples in examples/msg/actions/actions.c for details. + + */ - \section MSG_examples Examples of MSG - - \ref MSG_ex_master_slave - - \ref MSG_ex_asynchronous_communications - - \ref MSG_ex_master_slave_scrip_lua -*/ + +/** +@defgroup MSG_LUA Lua bindings +@ingroup MSG_API +@brief Lua bindings to MSG (\ref MSG_API) -/** @addtogroup MSG_LUA +@htmlonly @endhtmlonly + +This is the lua bindings of the \ref MSG_API interface. - \section MSG_Lua_funct Lua offered functionnalities in MSG - - \ref host_management - - \ref tasks_management - - \ref environment_management - \section Lua_examples Examples of lua MSG +\section lMSG_who Who should use this (and who shouldn't) + +If you want to use MSG to study your algorithm, but you don't want to +use the C language (using \ref MSG_API), then you should use some +bindings such as this one. The advantage of the lua bindings is that +they are distributed directly with the main archive (in contrary to +Java and Ruby bindings, for example, that are distributed separately). +Another advantage of lua is that there is almost no performance loss +with regard to the C version (at least there shouln't be any -- it is +still to be precisely assessed). + +\section MSG_Lua_funct Lua offered functionnalities in MSG + +Almost all important features of the MSG interface are available from +the lua bindings. Unfortunately, since doxygen does not support the +lua modules implemented directly in C as we are using, there is no +ready to use reference documentation for this module. Even more than +for the other modules, you will have to dig into the source code of +the examples to learn how to use it. + +\section Lua_examples Examples of lua MSG - - \ref MSG_ex_master_slave_lua - - \ref MSG_ex_master_slave_lua_bypass + - \ref MSG_ex_master_slave_lua + - \ref MSG_ex_master_slave_lua_bypass + - Also, the lua version of the Chord example (in the source tree) + is a working non-trivial example of use of the lua bindings */ +/** +@defgroup msg_deprecated_functions MSG Deprecated +@ingroup MSG_API +@brief This section describes the deprecated functions. PLEASE STOP USING THEM. + +We don't remove them because the ability to run old scientific +code is something important to us. But these functionalities are +not actively supported anymore. -/** @defgroup m_datatypes_management MSG Data Types - @ingroup MSG_C - @brief This section describes the different datatypes provided by MSG. - - \htmlonly \endhtmlonly -*/ -/** \addtogroup m_process_management - \ingroup MSG_C */ -/** \addtogroup m_host_management - \ingroup MSG_C */ -/** \addtogroup m_task_management - \ingroup MSG_C */ -/** \addtogroup msg_gos_functions - \ingroup MSG_C */ -/** \addtogroup m_channel_management - \ingroup MSG_C */ -/** \addtogroup msg_easier_life - \ingroup MSG_C */ -/** \addtogroup msg_simulation - \ingroup MSG_C */ - - -/** \page MSG_ex_asynchronous_communications Asynchronous communication applications - - Simulation of asynchronous communications between a sender and a receiver using a realistic platform and - an external description of the deployment. - - \section MSG_ex_ms_TOC Table of contents: - - \ref MSG_ext_icomms_code - - \ref MSG_ext_icomms_preliminary - - \ref MSG_ext_icomms_Sender - - \ref MSG_ext_icomms_Receiver - - \ref MSG_ext_icomms_core - - \ref MSG_ext_icomms_Main - - \ref MSG_ext_icomms_fct_Waitall - - \ref MSG_ext_icomms_fct_Waitany - -
- - \dontinclude msg/icomms/peer.c +To access these functions, you should define the relevant option +at configuration time in ccmake. + */ - \section MSG_ext_icomms_code Code of the application - \subsection MSG_ext_icomms_preliminary Preliminary declarations - \skip include - \until Sender function +/** +@defgroup MSG_ex_asynchronous_communications Asynchronous communications +@ingroup MSG_examples - \subsection MSG_ext_icomms_Sender Sender function +Simulation of asynchronous communications between a sender and a receiver using a realistic platform and +an external description of the deployment. - The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking - we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()". - It also available to "make MSG_comm_wait()" which make both of them. +\section MSG_ex_ms_TOC Table of contents: + - \ref MSG_ext_icomms_code + - \ref MSG_ext_icomms_preliminary + - \ref MSG_ext_icomms_Sender + - \ref MSG_ext_icomms_Receiver + - \ref MSG_ext_icomms_core + - \ref MSG_ext_icomms_Main + - \ref MSG_ext_icomms_fct_Waitall + - \ref MSG_ext_icomms_fct_Waitany - C style arguments (argc/argv) are interpreted as: - - the number of tasks to distribute - - the computation size of each task - - the size of the files associated to each task - - a list of host that will accept those tasks. - - the time to sleep at the beginning of the function - - This time defined the process sleep time +
+ +\dontinclude msg/icomms/peer.c + +\section MSG_ext_icomms_code Code of the application + +\subsection MSG_ext_icomms_preliminary Preliminary declarations +\skip include +\until Sender function + +\subsection MSG_ext_icomms_Sender Sender function + +The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking +we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()". +It also available to "make MSG_comm_wait()" which make both of them. + + C style arguments (argc/argv) are interpreted as: + - the number of tasks to distribute + - the computation size of each task + - the size of the files associated to each task + - a list of host that will accept those tasks. + - the time to sleep at the beginning of the function + - This time defined the process sleep time if time = 0 use of MSG_comm_wait() if time > 0 use of MSG_comm_test() - \until Receiver function +\until Receiver function - \subsection MSG_ext_icomms_Receiver Receiver function +\subsection MSG_ext_icomms_Receiver Receiver function - This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know - if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()". +This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know +if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()". - C style arguments (argc/argv) are interpreted as: - - the id to use for received the communication. - - the time to sleep at the beginning of the function - - This time defined the process sleep time + C style arguments (argc/argv) are interpreted as: + - the id to use for received the communication. + - the time to sleep at the beginning of the function + - This time defined the process sleep time if time = 0 use of MSG_comm_wait() if time > 0 use of MSG_comm_test() - \until Test function +\until Test function - \subsection MSG_ext_icomms_core Simulation core +\subsection MSG_ext_icomms_core Simulation core - This function is the core of the simulation and is divided only into 3 parts - thanks to MSG_create_environment() and MSG_launch_application(). - -# Simulation settings : MSG_create_environment() creates a realistic - environment - -# Application deployment : create the agents on the right locations with - MSG_launch_application() - -# The simulation is run with #MSG_main() + This function is the core of the simulation and is divided only into 3 parts + thanks to MSG_create_environment() and MSG_launch_application(). + -# Simulation settings : MSG_create_environment() creates a realistic + environment + -# Application deployment : create the processes on the right locations with + MSG_launch_application() + -# The simulation is run with #MSG_main() - Its arguments are: + Its arguments are: - platform_file: the name of a file containing an valid surfxml platform description. - application_file: the name of a file containing a valid surfxml application description - \until Main function +\until Main function - \subsection MSG_ext_icomms_Main Main function +\subsection MSG_ext_icomms_Main Main function - This initializes MSG, runs a simulation, and free all data-structures created by MSG. +This initializes MSG, runs a simulation, and free all data-structures created by MSG. - \until end_of_main +\until end_of_main - \dontinclude msg/icomms/peer2.c +\dontinclude msg/icomms/peer2.c - \section MSG_ext_icomms_fct_Waitall 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. +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 +\skipline Sender function +\until end_of_sender - \section MSG_ext_icomms_fct_Waitany Waitany function +\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. +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_sender From a sender +We can use this function to wait all sent 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 +\subsection MSG_ext_icomms_fct_Waitany_receiver From a receiver +We can also wait for the arrival 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 - - Simulation of a master-slave application using a realistic platform and - an external description of the deployment via a lua script. - - \section MSG_ex_msl_TOC Table of contents: - - - \ref MSG_ext_msl_code - - \ref MSG_ext_msl_preliminary - - \ref MSG_ext_msl_master - - \ref MSG_ext_msl_slave - - \ref MSG_ext_msl_core - - \ref MSG_ext_msl_main - - \ref MSG_ext_msl_helping - - \ref MSG_ext_msl_platform - -
- - \dontinclude msg/masterslave/masterslave_console.c - - \section MSG_ext_msl_code Code of the application +/** +@defgroup MSG_ex_master_slave Basic Master/Slaves +@ingroup MSG_examples - \subsection MSG_ext_msl_preliminary Preliminary declarations - - \skip include - \until } channel_t; - - \subsection MSG_ext_msl_master Master code - - This function has to be assigned to a m_process_t that will behave as the master. - It should not be called directly but either given as a parameter to - #MSG_process_create() or registered as a public function through - #MSG_function_register() and then automatically assigned to a process through - #MSG_load_platform_script(). - - C style arguments (argc/argv) are interpreted as: - - the number of tasks to distribute - - the computation size of each task - - the size of the files associated to each task - - number of hosts that will accept those tasks. +Simulation of a master-slave application using a realistic platform +and an external description of the deployment. - Tasks are dumbly sent in a round-robin style. - - \until end_of_master -\subsection MSG_ext_msl_slave Slave code +\section MSG_ex_ms_TOC Table of contents: - This function has to be assigned to a #m_process_t that has to behave as a slave. - Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly. - - This function keeps waiting for tasks and executes them as it receives them. - - \until end_of_slave - -\subsection MSG_ext_msl_core Simulation core - - This function is the core of the simulation and is divided now only into 2 parts - thanks to MSG_load_platform_script(). - -# Simulation settings and application deployment : MSG_load_platform_script() loads and creates a realistic - environment and the agents on the right locations, described in the lua script file (see example below). - Note that the use of this function require a lua installation on your machine. - -# The simulation is run with #MSG_main(). - - Its arguments are: - - platform_script_file: the name of the script file containing a valid platform and application description, using bound lua methods to bypass the surfxml parser. - - \until end_of_test_all - -\subsection MSG_ext_msl_main Main() function - - This initializes MSG, runs a simulation, and free all data-structures created by MSG. - - \until end_of_main - - \section MSG_ext_msl_helping Helping files - - \subsection MSG_ext_msl_platform Example of platform script file + - \ref MSG_ext_ms_code + - \ref MSG_ext_ms_preliminary + - \ref MSG_ext_ms_master + - \ref MSG_ext_ms_slave + - \ref MSG_ext_ms_forwarder + - \ref MSG_ext_ms_core + - \ref MSG_ext_ms_main + - \ref MSG_ext_ms_helping + - \ref MSG_ext_ms_application + - \ref MSG_ext_ms_platform + +
- \include msg/masterslave/platform_script.lua +\dontinclude msg/masterslave/masterslave_forwarder.c +\section MSG_ext_ms_code Code of the application -*/ +\subsection MSG_ext_ms_preliminary Preliminary declarations -/** \page MSG_ex_master_slave Master/slave application - - Simulation of a master-slave application using a realistic platform and - an external description of the deployment. +\skip include +\until printf +\until } - \section MSG_ex_ms_TOC Table of contents: - - - \ref MSG_ext_ms_code - - \ref MSG_ext_ms_preliminary - - \ref MSG_ext_ms_master - - \ref MSG_ext_ms_slave - - \ref MSG_ext_ms_forwarder - - \ref MSG_ext_ms_core - - \ref MSG_ext_ms_main - - \ref MSG_ext_ms_helping - - \ref MSG_ext_ms_application - - \ref MSG_ext_ms_platform - -
- - \dontinclude msg/masterslave/masterslave_forwarder.c - - \section MSG_ext_ms_code Code of the application - - \subsection MSG_ext_ms_preliminary Preliminary declarations - - \skip include - \until printf - \until } +\subsection MSG_ext_ms_master Master code - \subsection MSG_ext_ms_master Master code - - This function has to be assigned to a m_process_t that will behave as the master. - It should not be called directly but either given as a parameter to - #MSG_process_create() or registered as a public function through - #MSG_function_register() and then automatically assigned to a process through - #MSG_launch_application(). +This function has to be assigned to a m_process_t that will behave as +the master. It should not be called directly but either given as a +parameter to #MSG_process_create() or registered as a public function +through #MSG_function_register() and then automatically assigned to a +process through #MSG_launch_application(). - C style arguments (argc/argv) are interpreted as: - - the number of tasks to distribute - - the computation size of each task - - the size of the files associated to each task - - a list of host that will accept those tasks. +C style arguments (argc/argv) are interpreted as: + - the number of tasks to distribute + - the computation size of each task + - the size of the files associated to each task + - a list of host that will accept those tasks. - Tasks are dumbly sent in a round-robin style. +Tasks are dumbly sent in a round-robin style. - \until end_of_master +\until end_of_master - \subsection MSG_ext_ms_slave Slave code +\subsection MSG_ext_ms_slave Slave code - This function has to be assigned to a #m_process_t that has to behave as a slave. - Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly. +This function has to be assigned to a #m_process_t that has to behave +as a slave. Just like the master fuction (described in \ref +MSG_ext_ms_master), it should not be called directly. - This function keeps waiting for tasks and executes them as it receives them. +This function keeps waiting for tasks and executes them as it receives them. - \until end_of_slave +\until end_of_slave - \subsection MSG_ext_ms_forwarder Forwarder code +\subsection MSG_ext_ms_forwarder Forwarder code - This function has to be assigned to a #m_process_t that has to behave as a forwarder. - Just like the master function (described in \ref MSG_ext_ms_master), it should not be called directly. +This function has to be assigned to a #m_process_t that has to behave +as a forwarder. Just like the master function (described in \ref +MSG_ext_ms_master), it should not be called directly. - C style arguments (argc/argv) are interpreted as a list of host - that will accept those tasks. +C style arguments (argc/argv) are interpreted as a list of host that +will accept those tasks. - This function keeps waiting for tasks and dispathes them to its slaves. +This function keeps waiting for tasks and dispathes them to its slaves. - \until end_of_forwarder +\until end_of_forwarder - \subsection MSG_ext_ms_core Simulation core +\subsection MSG_ext_ms_core Simulation core - This function is the core of the simulation and is divided only into 3 parts - thanks to MSG_create_environment() and MSG_launch_application(). - -# Simulation settings : MSG_create_environment() creates a realistic - environment - -# Application deployment : create the agents on the right locations with - MSG_launch_application() - -# The simulation is run with #MSG_main() +This function is the core of the simulation and is divided only into 3 parts +thanks to MSG_create_environment() and MSG_launch_application(). + -# Simulation settings : MSG_create_environment() creates a realistic + environment + -# Application deployment : create the processes on the right locations with + MSG_launch_application() + -# The simulation is run with #MSG_main() - Its arguments are: +Its arguments are: - platform_file: the name of a file containing an valid surfxml platform description. - application_file: the name of a file containing a valid surfxml application description - \until end_of_test_all +\until end_of_test_all - \subsection MSG_ext_ms_main Main() function +\subsection MSG_ext_ms_main Main() function - This initializes MSG, runs a simulation, and free all data-structures created by MSG. +This initializes MSG, runs a simulation, and free all data-structures created by MSG. - \until end_of_main +\until end_of_main - \section MSG_ext_ms_helping Helping files +\section MSG_ext_ms_helping Helping files - \subsection MSG_ext_ms_application Example of application file +\subsection MSG_ext_ms_application Example of application file - \include msg/masterslave/deployment_masterslave.xml +\include msg/masterslave/deployment_masterslave.xml - \subsection MSG_ext_ms_platform Example of platform file - - \include msg/small_platform.xml +\subsection MSG_ext_ms_platform Example of platform file + +\include msg/small_platform.xml */ @@ -457,7 +433,7 @@ -# Simulation settings : simgrid.platform creates a realistic environment - -# Application deployment : create the agents on the right locations with + -# Application deployment : create the processes on the right locations with simgrid.application -# The simulation is run with simgrid.run @@ -520,3 +496,4 @@ \until simgrid.clean() */ +