X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/7da2926d0733ff0683f31aeea176ce71e127264f..92661d62eaee255e5f677a667c0f05a4f5917c24:/doc/doxygen/examples.doc diff --git a/doc/doxygen/examples.doc b/doc/doxygen/examples.doc index ef4a8ae531..8718864768 100644 --- a/doc/doxygen/examples.doc +++ b/doc/doxygen/examples.doc @@ -1,14 +1,9 @@ /*! \page examples SimGrid Examples -\note - This page is under work -- sorry for the inconvenience (FIXME). - -- @ref help - \tableofcontents SimGrid comes with many examples provided in the examples/ directory. -Those examples are described in section \ref MSG_examples. Those +Those examples are described in section \ref msg_examples. Those examples are commented and should be easy to understand. for a first step into SimGrid we also provide some more detailed examples in the sections below. @@ -31,213 +26,174 @@ example from which you can learn what you want to. \subsection MSG_ex_basics Basic examples and features -\subsubsection MSG_ex_asynchronous_communications Asynchronous communications +\subsubsection MSG_ex_master_worker Basic Master/Workers +Simulation of a master-worker application using a realistic platform and an external description of the deployment. -Simulation of asynchronous communications between a sender and a receiver using a realistic platform and -an external description of the deployment. +\paragraph MSG_ex_mw_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 + - \ref MSG_ext_mw_preliminary + - \ref MSG_ext_mw_master + - \ref MSG_ext_mw_worker + - \ref MSG_ext_mw_core + - \ref MSG_ext_mw_platform + - \ref MSG_ext_mw_application
-\dontinclude msg/icomms/peer.c +\dontinclude msg/app-masterworker/app-masterworker.c -\paragraph MSG_ext_icomms_code Code of the application +\paragraph MSG_ext_mw_preliminary Preliminary declarations -\paragraph MSG_ext_icomms_preliminary Preliminary declarations \skip include -\until Sender function +\until example"); +\skipline Master expects -\paragraph MSG_ext_icomms_Sender Sender function +\paragraph MSG_ext_mw_master Master code -A host can send an an asynchronous message with \c MSG_task_isend(). %As this function is non-blocking, -we have to call \c MSG_comm_test() to know if the communication has finished and finally destroy it with a call to \c MSG_comm_destroy(). -It is also possible to call \c MSG_comm_wait() which, is provides a shortcut. +This function has to be assigned to a #msg_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: +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 - -\paragraph 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 \c MSG_comm_test() or wait for the completion \c 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 - if time = 0 use of MSG_comm_wait() - if time > 0 use of MSG_comm_test() + - the computational size of each task + - the communication size of each task + - the number of workers managed by the master. -\until Test function +Tasks are evenly sent in a round-robin style. -\paragraph 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 processes on the right locations with - MSG_launch_application() - -# The simulation is run with #MSG_main() - - 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 return 0; +\until } +\skipline Worker expects -\until Main function +\paragraph MSG_ext_mw_worker Worker code -\paragraph MSG_ext_icomms_Main Main function +This function has to be assigned to a #msg_process_t that has to behave as a worker. Just like the master function +(described in \ref MSG_ext_mw_master), it should not be called directly. -This initializes MSG, runs a simulation, and free all data-structures created by MSG. +C style arguments (argc/argv) are interpreted as: + - a unique id used to build the mailbox name of the worker -\until end_of_main +This function keeps waiting for tasks and executes them as it receives them. When a special task named 'finalize' is +received from the master, the process ends its execution. -\dontinclude msg/icomms/peer2.c +\until return 0; +\until } -\paragraph MSG_ext_icomms_fct_Waitall Waitall function for sender +\paragraph MSG_ext_mw_core Main function -The use of this function permit to send all messages and wait for the completion of all in one time. +This function is the core of the simulation and is divided only into 3 parts: + -# 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() -\skipline Sender function -\until end_of_sender +Its arguments are: + - platform_file: the name of a file containing an valid platform description. + - deployment_file: the name of a file containing a valid application description +\line main +\until OK; +\until } -\paragraph MSG_ext_icomms_fct_Waitany Waitany function +\paragraph MSG_ext_mw_platform Example of a platform file -The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table. +The following platform description can be found in \c examples/msg/platforms/small_platform.xml +\include platforms/small_platform.xml -\paragraph 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 +\paragraph MSG_ext_mw_application Example of a deployment file -\paragraph 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 +The following application description can be found in \c examples/msg/app-masterworker/app-masterworker_d.xml: -\subsubsection MSG_ex_master_slave Basic Master/Slaves +\include msg/app-masterworker/app-masterworker_d.xml -Simulation of a master-slave application using a realistic platform -and an external description of the deployment. +\subsubsection MSG_ex_asynchronous_communications Asynchronous communications -\paragraph MSG_ex_ms_TOC Table of contents: +Simulation of asynchronous communications between a sender and a receiver using a realistic platform and +an external description of the deployment. - - \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 + - \ref MSG_ext_async_code + - \ref MSG_ext_async_preliminary + - \ref MSG_ext_async_Sender + - \ref MSG_ext_async_Receiver + - \ref MSG_ext_async_Main + - \ref MSG_ext_async_fct_Waitall + - \ref MSG_ext_async_fct_Waitany
-\dontinclude msg/masterslave/masterslave_forwarder.c +\dontinclude msg/async-wait/async-wait.c +\paragraph MSG_ext_async_code Code of the application -\paragraph MSG_ext_ms_preliminary Preliminary declarations - +\paragraph MSG_ext_async_preliminary Preliminary declarations \skip include -\until printf -\until } +\until Sender -\paragraph MSG_ext_ms_master Master code +\paragraph MSG_ext_async_Sender Sender function -This function has to be assigned to a #msg_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(). +A host can send an asynchronous message with \c MSG_task_isend(). As this function is non-blocking, we have to call +\c MSG_comm_test() to know if the communication is complete and evenetually destroy it with a call to +\c MSG_comm_destroy(). It is also possible to call \c MSG_comm_wait() which provides a shortcut. -C style arguments (argc/argv) are interpreted as: + 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. - -\until end_of_master - -\paragraph MSG_ext_ms_slave Slave code - -This function has to be assigned to a #msg_process_t that has to behave -as a slave. Just like the master function (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 - -\paragraph MSG_ext_ms_forwarder Forwarder code - -This function has to be assigned to a #msg_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. + - the number of receivers that will accept those tasks + - the time to sleep at the beginning of the function. This time defines the process sleep time: + - if time = 0, use MSG_comm_wait() + - if time > 0, use MSG_comm_test() -C style arguments (argc/argv) are interpreted as a list of hosts that -will accept those tasks. +\until Receiver -This function keeps waiting for tasks and dispatches them to its slaves. +\paragraph MSG_ext_async_Receiver Receiver function -\until end_of_forwarder +This function executes tasks when it receives them. As the receiving is asynchronous, we have to test the completion of +the communication with \c MSG_comm_test() or wait for it with \c MSG_comm_wait(). -\paragraph MSG_ext_ms_core Simulation core + 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() -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() +\until return +\until } -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 +\paragraph MSG_ext_async_Main Main function -\until end_of_test_all +This function is the core of the simulation and is divided only into 3 parts: + -# Simulation settings : MSG_create_environment() loads a platform description + -# Application deployment : create the processes on the right locations with MSG_launch_application() + -# The simulation is run with #MSG_main() -\paragraph MSG_ext_ms_main Main() function + Its arguments are: + - platform_file: the name of a file containing an valid platform description. + - application_file: the name of a file containing a valid application deployment. -This initializes MSG, runs a simulation, and free all data-structures created by MSG. +\until return +\until } -\until end_of_main +\dontinclude msg/async-waitall/async-waitall.c -\subsubsection MSG_ext_ms_helping Helping files +\paragraph MSG_ext_async_fct_Waitall Waitall function -\paragraph MSG_ext_ms_application Example of a deployment file +The use of MSG_comm_waitall() allows a process to send all the tasks and then wait for the completion of all in one call. -The following listing can be found in \c examples/msg/masterslave/deployment_masterslave_forwarder.xml: +\skipline static +\until return +\until } -\include msg/masterslave/deployment_masterslave_forwarder.xml +\paragraph MSG_ext_async_fct_Waitany Waitany function -\paragraph MSG_ext_ms_platform Example of a platform file +The MSG_comm_waitany() function returns the place of the first message send or receive from a xbt_dynar. -\include platforms/small_platform.xml +\skipline static +\until return +\until } */