+++ /dev/null
-/*! \page use Using SimGrid
-
-\section using_msg Using MSG
-
-Here are some examples on how to use MSG, the most used 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.
-
-\subsection MSG_ex_basics Basic examples and features
-
-\subsubsection MSG_ex_asynchronous_communications Asynchronous communications
-
-
-Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
-an external description of the deployment.
-
- - \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
-
-<hr>
-
-\dontinclude msg/icomms/peer.c
-
-\paragraph MSG_ext_icomms_code Code of the application
-
-\paragraph MSG_ext_icomms_preliminary Preliminary declarations
-\skip include
-\until Sender function
-
-\paragraph 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
-
-\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 "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
- if time = 0 use of MSG_comm_wait()
- if time > 0 use of MSG_comm_test()
-
-\until Test function
-
-\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:
- - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
- - <i>application_file</i>: the name of a file containing a valid surfxml application description
-
-\until Main function
-
-\paragraph MSG_ext_icomms_Main Main function
-
-This initializes MSG, runs a simulation, and free all data-structures created by MSG.
-
-\until end_of_main
-
-\dontinclude msg/icomms/peer2.c
-
-\paragraph 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
-
-\paragraph 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.
-
-\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_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
-
-\subsubsection MSG_ex_master_slave Basic Master/Slaves
-
-Simulation of a master-slave application using a realistic platform
-and an external description of the deployment.
-
-\paragraph MSG_ex_ms_TOC Table of contents:
-
- - \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
-
-<hr>
-
-\dontinclude msg/masterslave/masterslave_forwarder.c
-
-
-\paragraph MSG_ext_ms_preliminary Preliminary declarations
-
-\skip include
-\until printf
-\until }
-
-\paragraph 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().
-
-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 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
-
-\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.
-
-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.
-
-\until end_of_forwarder
-
-\paragraph 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 processes on the right locations with
- MSG_launch_application()
- -# The simulation is run with #MSG_main()
-
-Its arguments are:
- - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
- - <i>application_file</i>: the name of a file containing a valid surfxml application description
-
-\until end_of_test_all
-
-\paragraph MSG_ext_ms_main Main() function
-
-This initializes MSG, runs a simulation, and free all data-structures created by MSG.
-
-\until end_of_main
-
-\subsubsection MSG_ext_ms_helping Helping files
-
-\paragraph MSG_ext_ms_application Example of application file
-
-\include msg/masterslave/deployment_masterslave.xml
-
-\paragraph MSG_ext_ms_platform Example of platform file
-
-\include msg/small_platform.xml
-
-\section using_gras Using GRAS
-
-Here are some examples on how to use GRAS.
-
-
- There is for now rather few examples of GRAS, but it's better than
- nothing, isn't it?
-
- - \ref GRAS_ex_ping
- - \ref GRAS_ex_mmrpc
- - \ref GRAS_ex_token
- - \ref GRAS_ex_timer
-
-
-\subsection GRAS_ex_ping Ping-Pong
-
- This example implements the very classical ping-pong in GRAS. It
- involves a client (initiating the ping-pong) and a server (answering to
- client's requests).
-
- It works the following way:
- - Both the client and the server register all needed messages
- - The server registers a callback to the ping message, which sends pong
- to the expeditor
- - The client sends the ping message to the server, and waits for the
- pong message as an answer.
-
- This example resides in the <b>examples/gras/ping/ping.c</b> file. Yes, both
- the code of the client and of the server is placed in the same file.
-
- \subsubsection GRAS_ex_ping_toc Table of contents of the ping example
- - \ref GRAS_ex_ping_common
- - \ref GRAS_ex_ping_initial
- - \ref GRAS_ex_ping_register
- - \ref GRAS_ex_ping_server
- - \ref GRAS_ex_ping_serdata
- - \ref GRAS_ex_ping_sercb
- - \ref GRAS_ex_ping_sermain
- - \ref GRAS_ex_ping_client
- - \ref GRAS_ex_ping_climain
-
- <hr>
-
- \dontinclude gras/ping/ping_common.c
-
- \subsubsection GRAS_ex_ping_common 1) Common code to the client and the server
-
- \paragraph GRAS_ex_ping_initial 1.a) Initial settings
-
- Let's first load the module header and declare a logging category (see
- \ref XBT_log for more info on logging).
-
- \skip include
- \until XBT_LOG
-
- The module header <tt>ping.h</tt> reads:
-
- \dontinclude gras/ping/ping.h
- \skip include
- \until argv
- \until argv
-
- \paragraph GRAS_ex_ping_register 1.b) Register the messages
-
- This function, called by both the client and the server is in charge of
- declaring the existing messages to GRAS. Since the payload does not
- involve any newly created types but only int, this is quite easy.
- (to exchange more complicated types, see \ref GRAS_dd or
- \ref GRAS_ex_mmrpc for an example).
-
- \dontinclude gras/ping/ping_common.c
- \skip register_messages
- \until }
-
- [Back to \ref GRAS_ex_ping_toc]
-
- \subsubsection GRAS_ex_ping_server 2) Server's code
-
- \paragraph GRAS_ex_ping_serdata 2.a) The server's globals
-
- In order to ensure the communication between the "main" and the callback
- of the server, we need to declare some globals. We have to put them in a
- struct definition so that they can be handled properly in GRAS.
-
- \dontinclude gras/ping/ping_server.c
- \skip typedef struct
- \until }
-
- \paragraph GRAS_ex_ping_sercb 2.b) The callback to the ping message
-
- Here is the callback run when the server receives any ping message (this
- will be registered later by the server).
-
- \skip server_cb_ping_handler
- \until end_of_server_cb_ping_handler
-
- \paragraph GRAS_ex_ping_sermain 2.c) The "main" of the server
-
- This is the "main" of the server. You must not write any main()
- function yourself. Instead, you just have to write a regular function
- like this one which will act as a main.
-
- \skip server
- \until end_of_server
-
- [Back to \ref GRAS_ex_ping_toc]
-
- \subsubsection GRAS_ex_ping_client 3) Client's code
-
- \paragraph GRAS_ex_ping_climain 3.a) Client's "main" function
-
- This function is quite straightforward, and the inlined comments should
- be enough to understand it.
-
- \dontinclude gras/ping/ping_client.c
- \skip client
- \until end_of_client
-
- [Back to \ref GRAS_ex_ping_toc]
-
-\subsection GRAS_ex_token Token Ring example
-
- This example implements the token ring algorithm. It involves several
- nodes arranged in a ring (each of them have a left and a right neighbour)
- and exchanging a "token". This algorithm is one of the solution to ensure
- the mutual exclusion between distributed processes. There is only one
- token at any time, so the process in its possession is ensured to be the
- only one having it. So, if there is an action you want all processes to
- do alternativly, but you cannot afford to have two processes doing it at
- the same time, let the process having the token doing it.
-
- Actually, there is a lot of different token ring algorithms in the
- litterature, so this example implements one of them: the simplest one.
- The ring is static (no new node can join it, and you'll get trouble if
- one node dies or leaves), and nothing is done for the case in which the
- token is lost.
-
- - \ref GRAS_ex_stoken_deploy
- - \ref GRAS_ex_stoken_global
- - \ref GRAS_ex_stoken_callback
- - \ref GRAS_ex_stoken_main
-
- \subsection GRAS_ex_stoken_deploy 1) Deployment file
-
- Here is the deployment file:
- \include examples/gras/mutual_exclusion/simple_token/simple_token.xml
-
- The neighbour of each node is given at startup as command line argument.
- Moreover, one of the nodes is instructed by a specific argument (the one
- on Tremblay here) to create the token at the begining of the algorithm.
-
- \subsection GRAS_ex_stoken_global 2) Global definition
-
- The token is incarned by a specific message, which circulates from node
- to node (the payload is an integer incremented at each hop). So, the most
- important part of the code is the message callback, which forwards the
- message to the next node. That is why we have to store all variable in a
- global, as explained in the \ref GRAS_globals section.
-
- \dontinclude examples/gras/mutual_exclusion/simple_token/simple_token.c
- \skip typedef
- \until }
-
- \subsection GRAS_ex_stoken_callback 3) The callback
-
- Even if this is the core of this algorithm, this function is quite
- straightforward.
-
- \skip node_cb_stoken_handler
- \until end_of_node_cb_stoken_handler
-
- \subsection GRAS_ex_stoken_main 4) The main function
-
- This function is splited in two parts: The first one performs all the
- needed initialisations (points 1-7) while the end (point 8. below) calls
- gras_msg_handle() as long as the planned amount of ring loops are not
- performed.
-
- \skip node
- \until end_of_node
-
-\subsection GRAS_ex_mmrpc A simple RPC for matrix multiplication
-
- This example implements a remote matrix multiplication. It involves a client
- (creating the matrices and sending the multiplications requests) and a server
- (computing the multiplication on client's behalf).
-
- This example also constitutes a more advanced example of data description
- mechanisms, since the message payload type is a bit more complicated than in
- other examples such as the ping one (\ref GRAS_ex_ping).
-
- It works the following way (not very different from the ping example):
- - Both the client and the server register all needed messages and datatypes
- - The server registers a callback to the "request" message, which computes
- what needs to be and returns the result to the expeditor.
- - The client creates two matrices, ask for their multiplication and check
- the server's answer.
-
- This example resides in the <b>examples/gras/mmrpc/mmrpc.c</b> file.
-
- \subsubsection GRAS_ex_mmrpc_toc Table of contents of the mmrpc example
- - \ref GRAS_ex_mmrpc_common
- - \ref GRAS_ex_mmrpc_header
- - \ref GRAS_ex_mmrpc_dataregister
- - \ref GRAS_ex_mmrpc_logdef
- - \ref GRAS_ex_mmrpc_msgregister
- - \ref GRAS_ex_mmrpc_server
- - \ref GRAS_ex_mmrpc_serinc
- - \ref GRAS_ex_mmrpc_sercb
- - \ref GRAS_ex_mmrpc_sermain
- - \ref GRAS_ex_mmrpc_client
- - \ref GRAS_ex_mmrpc_cliinc
- - \ref GRAS_ex_mmrpc_climain
-
- <hr>
-
-
- \subsubsection GRAS_ex_mmrpc_common 1) Common code to the client and the server (mmrpc_common.c and mmrpc.h)
-
-
- \paragraph GRAS_ex_mmrpc_header 1.a) Module header (mmrpc.h)
-
- This loads the gras header and declare the function's prototypes as well
- as the matrix size.
-
- \dontinclude gras/mmrpc/mmrpc.h
- \skip include
- \until argv
- \until argv
-
- \paragraph GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h)
-
- The messages involved in a matrix of double. This type is automatically
- known by the GRAS mecanism, using the gras_datadesc_matrix() function of the
- xbt/matrix module.
-
- \paragraph GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c)
-
- Let's first load the module header and declare a logging category (see
- \ref XBT_log for more info on logging). This logging category does live
- in this file (ie the required symbols are defined here and declared as
- "extern" in any other file using them). That is why we use
- \ref XBT_LOG_NEW_DEFAULT_CATEGORY here and
- \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY in mmrpc_client.c and mmrpc_server.c.
-
- \dontinclude gras/mmrpc/mmrpc_common.c
- \skip include
- \until XBT_LOG
-
- \paragraph GRAS_ex_mmrpc_msgregister 1.d) Register the messages (mmrpc_common.c)
-
- This function, called by both the client and the server is in charge of
- declaring the existing messages to GRAS.
-
- The datatype description builded that way can then be used to build an array datatype or
- to declare messages.
-
- \skip register_messages
- \until }
-
- [Back to \ref GRAS_ex_mmrpc_toc]
-
- \subsubsection GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)
-
- \paragraph GRAS_ex_mmrpc_serinc 2.a) Server intial settings
-
- All module symbols live in the mmrpc_common.c file. We thus have to
- define \ref XBT_DEFINE_TYPE_EXTERN to the preprocessor so that the
- \ref XBT_DEFINE_TYPE symbols don't get included here. Likewise, we use
- \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY to get the log category in here.
-
- \dontinclude gras/mmrpc/mmrpc_server.c
- \skip define
- \until XBT_LOG
-
- \paragraph GRAS_ex_mmrpc_sercb 2.b) The callback to the mmrpc message
-
- Here is the callback run when the server receives any mmrpc message (this
- will be registered later by the server). Note the way we get the message
- payload. In the ping example, there was one additional level of pointer
- indirection (see \ref GRAS_ex_ping_sercb). This is because the payload is
- an array here (ie a pointer) whereas it is a scalar in the ping example.
-
- \skip server_cb_request_handler
- \until end_of_server_cb_request_handler
-
- \paragraph GRAS_ex_mmrpc_sermain 2.c) The "main" of the server
-
- This is the "main" of the server. You must not write any main()
- function yourself. Instead, you just have to write a regular function
- like this one which will act as a main.
-
- \skip server
- \until end_of_server
-
- [Back to \ref GRAS_ex_mmrpc_toc]
-
- \subsubsection GRAS_ex_mmrpc_client 3) Client's code (mmrpc_client.c)
-
- \paragraph GRAS_ex_mmrpc_cliinc 2.a) Server intial settings
-
- As for the server, some extra love is needed to make sure that automatic
- datatype parsing and log categories do work even if we are using several
- files.
-
- \dontinclude gras/mmrpc/mmrpc_client.c
- \skip define
- \until XBT_LOG
-
- \paragraph GRAS_ex_mmrpc_climain 3.b) Client's "main" function
-
- This function is quite straightforward, and the inlined comments should
- be enough to understand it.
-
- \dontinclude gras/mmrpc/mmrpc_client.c
- \skip argv
- \until end_of_client
-
- [Back to \ref GRAS_ex_mmrpc_toc]
-
-\subsection GRAS_ex_timer Some timer games
-
- This example fools around with the GRAS timers (\ref GRAS_timer). It is
- mainly a regression test, since it uses almost all timer features.
-
- The main program registers a repetititive task and a delayed one, and
- then loops until the <tt>still_to_do</tt> variables of its globals reach
- 0. The delayed task set it to 5, and the repetititive one decrease it
- each time. Here is an example of output:
-\verbatim Initialize GRAS
- Initialize XBT
- [1108335471] Programming the repetitive_action with a frequency of 1.000000 sec
- [1108335471] Programming the delayed_action for after 2.000000 sec
- [1108335471] Have a rest
- [1108335472] Canceling the delayed_action.
- [1108335472] Re-programming the delayed_action for after 2.000000 sec
- [1108335472] Repetitive_action has nothing to do yet
- [1108335473] Repetitive_action has nothing to do yet
- [1108335473] delayed_action setting globals->still_to_do to 5
- [1108335474] repetitive_action decrementing globals->still_to_do. New value: 4
- [1108335475] repetitive_action decrementing globals->still_to_do. New value: 3
- [1108335476] repetitive_action decrementing globals->still_to_do. New value: 2
- [1108335477] repetitive_action decrementing globals->still_to_do. New value: 1
- [1108335478] repetitive_action decrementing globals->still_to_do. New value: 0
- Exiting GRAS\endverbatim
-
- Source code:
- - \ref GRAS_ex_timer_decl
- - \ref GRAS_ex_timer_delay
- - \ref GRAS_ex_timer_repeat
- - \ref GRAS_ex_timer_main
-
- \dontinclude timer.c
-
- \subsubsection GRAS_ex_timer_decl 1. Declarations and headers
- \skip include
- \until my_globals
-
- \subsubsection GRAS_ex_timer_delay 2. Source code of the delayed action
- \skip repetitive_action
- \until end_of_repetitive_action
-
- \subsubsection GRAS_ex_timer_repeat 3. Source code of the repetitive action
- \skip delayed_action
- \until end_of_delayed_action
-
- \subsubsection GRAS_ex_timer_main 4. Source code of main function
- \skip client
- \until end_of_client
-
-
-*/
-
-
