X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/39eaafd39429445bac3fb906bfde2714fc1dc848..b9e96fbb5cfd020bcb5624e581388258e75342bb:/doc/user_guide/doxygen/use.doc diff --git a/doc/user_guide/doxygen/use.doc b/doc/user_guide/doxygen/use.doc index ac288868ae..f5bbdc0e03 100644 --- a/doc/user_guide/doxygen/use.doc +++ b/doc/user_guide/doxygen/use.doc @@ -229,378 +229,6 @@ This initializes MSG, runs a simulation, and free all data-structures created by \include msg/small_platform.xml -\section using_gras Using GRAS - -Here are some examples on how to use GRAS. -\htmlonly -You should also check our online tutorial section that contains a dedicated tutorial. -\endhtmlonly - -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 examples/gras/ping/ping.c 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 - -
- - \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 ping.h 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 examples/gras/mmrpc/mmrpc.c 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 - -
- - - \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 still_to_do 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 - \section using_smpi Using SMPI You should check our online tutorial section that contains a dedicated tutorial.