X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/742212ec1266445079f959b75d347009e6881e3d..c95b043ca02f5d0fce244c47e530a12b6eb86de5:/doc/module-gras.doc diff --git a/doc/module-gras.doc b/doc/module-gras.doc index f2451f08f3..c91622e8a0 100644 --- a/doc/module-gras.doc +++ b/doc/module-gras.doc @@ -3,8 +3,20 @@ ##################################################################### /** \addtogroup GRAS_API - - \section GRAS_funct Offered functionnalities + +\htmlonly +
+
Table of content
+
    +
  1. API documentation +
  2. Examples +
  3. Tutorial +
  4. HOWTOs +
+\endhtmlonly + + \section GRAS_funct API documentation + GRAS offers the following functionnalities - \ref GRAS_comm: Exchanging messages between peers - \ref GRAS_dd : any data which may transit on the network must be described beforehand so that GRAS can handle the platform @@ -30,19 +42,7 @@ This is how to let GRAS handle your globals properly. - \ref GRAS_emul : Support to emulate code excution (ie, reporting execution time into the simulator and having code sections specific - to simulation or to real mode). - - \ref GRAS_code: Here are some tools which may help - you setting up a GRAS project.\n - Setting up and building a GRAS application is complicated by the - library schizoid. The code to setup the environment differs - depending on whether you run on the simulator on a real platform. - And then, you'll have to deal with the usual distributed - application development difficulties. - - \ref GRAS_main_generation : Since processes are threads in - simulation mode and regular processes in the real world, GRAS does - generate your main functions for you. - - \ref GRAS_compile - + to simulation or to real mode). \section GRAS_example Examples @@ -51,13 +51,55 @@ - \ref GRAS_ex_ping - \ref GRAS_ex_mmrpc + - \ref GRAS_ex_token - \ref GRAS_ex_timer - - @{ */ + + The initiatic tour of the tutorial also contains several examples. The + most proeminent one is: + + - \ref GRAS_tut_tour_explicitwait_use + + \section GRAS_tut_presentation Tutorial + + We even have a tutorial for the GRAS framework. It details in a + hopefully pedagogic order all the points of the API, along with example + of use for each of them. Unfortunately, it is not finished yet (the main + part missing is the one on how to describe data). Here is the table of + content: + + - \ref GRAS_tut_intro + - \ref GRAS_tut_intro_what + - \ref GRAS_tut_intro_model + - \ref GRAS_tut_tour + - \ref GRAS_tut_tour_install + - \ref GRAS_tut_tour_setup + - \ref GRAS_tut_tour_simpleexchange + - \ref GRAS_tut_tour_args + - \ref GRAS_tut_tour_callbacks + - \ref GRAS_tut_tour_globals + - \ref GRAS_tut_tour_logs + - \ref GRAS_tut_tour_timers + - \ref GRAS_tut_tour_exceptions + - \ref GRAS_tut_tour_rpc + - \ref GRAS_tut_tour_explicitwait + - \ref GRAS_tut_tour_message_recaping + + \section GRAS_howto_presentation HOWTOs + + The tutorial and the API documentation present the framework little + piece by little piece and provide a lot of information on each of them. + Quite orthogonally to this, the HOWTOs try to present transversal + aspects of the framework to give you some broader point of view on it. + How infortunate it is that only one such HOWTO exist for now... + + - \ref GRAS_howto + - \ref GRAS_howto_design + + @{ */ /** @defgroup GRAS_comm Communication facilities */ /** @defgroup GRAS_run Virtualization */ - /** @defgroup GRAS_code Project and code management */ /** @defgroup GRAS_ex Examples */ + /** @defgroup GRAS_tut GRAS Tutorial */ /** @} */ ##################################################################### /** @addtogroup GRAS_comm @@ -93,22 +135,6 @@ /** @} */ -##################################################################### -/** @addtogroup GRAS_code - - Here is how to setup your code when you want to use GRAS. You will also - learn how to get the most repetitive parts of your code generated - automatically. - - (use the tabs on top of the page to navigate) - - \htmlonly \endhtmlonly -*/ - ##################################################################### /** @addtogroup GRAS_ex @@ -117,11 +143,18 @@ - \ref GRAS_ex_ping - \ref GRAS_ex_mmrpc + - \ref GRAS_ex_token - \ref GRAS_ex_timer + The initiatic tour of the tutorial also contains several examples. The + most proeminent one is: + + - \ref GRAS_tut_tour_explicitwait_use + \htmlonly \endhtmlonly @@ -129,178 +162,6 @@ examples/gras. */ -##################################################################### -######################### EXTRA PAGES ############################## -##################################################################### - ---------------------------------------------------------------------- ---------------------- main() generation ----------------------------- ---------------------------------------------------------------------- - -/** \page GRAS_main_generation main function - - \section GRAS_maingen_toc Table of content - - - \ref GRAS_maingen_intro - - \ref GRAS_maingen_script - - \ref GRAS_maingen_make - -
- - \section GRAS_maingen_intro What's the matter with main() functions in GRAS? - - In simulation mode, all processes are run as thread of the same process - while they are real processes in the real life. Unfortunately, the main - function of a real process must be called main while this - function must not use this name for threads. - - To deal with this, you should call the main function of your processes - with another name (usually, the process function such as client, server, - or such). Then GRAS can generate the wrapper functions adapted to the - real and simulated modes. - - \section GRAS_maingen_script Generating the main()s automatically - - This is done by the gras_stub_generator program, which gets installed on - make install (the source resides in the tools/gras/ directory). - Here is the calling syntax: - \verbatim gras_stub_generator \endverbatim - - It parses the deployment file, searching for all the kind of processes - you have in your project. It then generates the following C files: - - a __.c file for each process kind you - have\n - They are used to launch your project in real life. They - contain a main() in charge of initializing the GRAS infrastructure and - launching your code afterward. - - a __simulator.c file.\n - This file is suited to the simulation mode. It contains a main() - function initializing the simulator and launching your project within. - - For this to work, the name of process described in your deployment file - should match the name of a function in your code, which prototype is for - example: \verbatim int client(int argc,char *argv[]);\endverbatim - - Unfortunately, all this is still partially documented. I guess I ought - to improve this situation somehow. In the meanwhile, check the generated - code and maybe also the GRAS \ref GRAS_example, sorry. - - \section GRAS_maingen_make Integration within an hand-made Makefile - - The easiest to set it up is to add the following chunk at the end of - your Makefile (or Makefile.am), putting the right values into NAME and - PROCESSES. -\verbatim NAME=your_project_name - PROCESSES=list of processes type in your project - - $(foreach proc, $(PROCESSES), _$(NAME)_$(proc).c) _$(NAME)_simulator.c: $(NAME).c $(NAME)_deployment.xml - path/to/gras_stub_generator $(NAME) $(NAME)_deployment.xml >/dev/null -\endverbatim - - Of course, your personal millage may vary. For the \ref GRAS_ex_ping, may read: -\verbatim _ping_client.c _ping_server.c _ping_simulator.c: ping.c ping_deployment.xml - $(top_srcdir)/tools/gras/gras_stub_generator ping ping_deployment.xml >/dev/null -\endverbatim - - \warning - Actually, gras_stub_generator also generates some makefiles both for - local compilation and remote code distribution and installation. See the - section \ref GRAS_compile for more details. - -*/ - ---------------------------------------------------------------------- -------------------------- Compiling --------------------------------- ---------------------------------------------------------------------- - -/** \page GRAS_compile Compiling your project - - As explained in section \ref GRAS_main_generation, the - gras_stub_generator tool can be used to generate the system - initialization code in your projet. While we were at this, this tool - also generates the makefiles you will need to compile your project - properly. - - Code source deployment and remote compilation also constitutes a - challenging area in distributed applications development. The GRASPE - (GRAS Platform Expender) tool was designed to make this less painful. - - \section GRAS_compile_toc Table of content - - - \ref GRAS_compile_local - - \ref GRAS_compile_local_install - - \ref GRAS_compile_local_helpfiles - - \ref GRAS_compile_local_makefile - - \ref GRAS_compile_remote - -
- - \section GRAS_compile_local Local compilation of GRAS projects - - \subsection GRAS_compile_local_install Installing SimGrid and GRAS - - To compile locally a GRAS project, you first need to install SimGrid on - your machine. Use the --prefix flag to the configure script to specify - where you want to install the toolkit (refere to section \ref - faq_compiling for more information) - - \subsection GRAS_compile_local_helpfiles Simulation description files - - Then, you will probably need to write a platform description file and - application deployment description file to feed the simulator with. This - part is unfortunatelly not documented enough. Files examples can be - found along with the MSG \ref MSG_ex_master_slave example. - - \note yes, both platform and application description files are portable - between MSG and GRAS. Actually, there depend on the SURF, not on the - programming environment you use. - - For the first try, you could probably reuse the provided platform file - as is while you will need to adapt the application file to fit your - needs. - - To generate new platform files, we usually use the Tiers Topology - Generator (ask google about it) and annotate the generated graph with - home-made scripts to let them fit the SURF. Those scripts live in the - tools/platform_generation/ directory of the distribution. - - \subsection GRAS_compile_local_makefile Generating a Makefile usable for your project - - From the information contained in the application description file, the - gras_stub_generator tool can create a Makefile which can be used to - seamlessly compile your project. Just go to the directory containing all - your project files, and type: - -\verbatim path/to/gras_stub_generator [project_name] [application_deployment.file] >/dev/null -\endverbatim - - The first argument is the name of your project, such as - "MyLovelyApplication" while the second one is the application deployment - file. - - Several files get generated by this command. One C file per kind of - process in your project (such as "master" and "slave") plus one C file - for simulating your project. All those files are (or should ;) described - in section \ref GRAS_main_generation. - - The most intersting file in this context is - [project_name].Makefile.local (you can safely ignore the others for - now). To use it, simply type (from your project main directory): - -\verbatim GRAS_ROOT=/path/to/simgrid/installation make -f [project_name].Makefile.local -\endverbatim - - And that's it, all the binaries are built and linked against the correct - libraries. - - \section GRAS_compile_remote Distribution and remote compilation of GRAS projects - - Actually, there is two somehow parallel ways to do so since both Arnaud - and Martin gave it a try. Merging both approaches is underway. As usual, - if you want to help, you're welcome ;) - -*/ - ##################################################################### ######################### EXAMPLES ################################# ##################################################################### @@ -324,7 +185,7 @@ 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. See - the \ref GRAS_main_generation section if wondering. + the \ref GRAS_tut_tour_setup of the tutorial if wondering. \section GRAS_ex_ping_toc Table of contents of the ping example - \ref GRAS_ex_ping_common @@ -379,7 +240,7 @@ 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 (see the - \ref GRAS_globals for more info). + \ref GRAS_tut_tour_globals for more info). \dontinclude gras/ping/ping_server.c \skip typedef struct @@ -395,8 +256,8 @@ \subsection GRAS_ex_ping_sermain 2.c) The "main" of the server - This is the "main" of the server. As explained in the \ref - GRAS_main_generation, you must not write any main() + This is the "main" of the server. As explained in the tutorial, \ref + GRAS_tut_tour_setup, 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. @@ -419,6 +280,73 @@ [Back to \ref GRAS_ex_ping_toc] */ +--------------------------------------------------------------------- +--------------------- Simple Token Ring ----------------------------- +--------------------------------------------------------------------- + +/** \page 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 + + \section 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. + + \section 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 } + + \section 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 + + \section 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 + +*/ + --------------------------------------------------------------------- -------------------------- MM RPC ----------------------------------- --------------------------------------------------------------------- @@ -441,7 +369,7 @@ the server's answer. This example resides in the examples/gras/mmrpc/mmrpc.c file. (See - the \ref GRAS_main_generation section if wondering why both the server + the \ref GRAS_tut_tour_setup of the tutorial if wondering why both the server and the client live in the same source file) \section GRAS_ex_mmrpc_toc Table of contents of the mmrpc example @@ -450,7 +378,6 @@ - \ref GRAS_ex_mmrpc_dataregister - \ref GRAS_ex_mmrpc_logdef - \ref GRAS_ex_mmrpc_msgregister - - \ref GRAS_ex_mmrpc_matdump - \ref GRAS_ex_mmrpc_server - \ref GRAS_ex_mmrpc_serinc - \ref GRAS_ex_mmrpc_sercb @@ -477,27 +404,9 @@ \subsection GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h) - The messages involved in this example do use structures as payload, - so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing - the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this - declaration into an hidden string variable, which can be automatically parsed at - run time. Of course, the declaration is also copied unmodified by this macro, so that it - gets parsed by the compiler also. - - There is some semantic that GRAS cannot guess alone and you need to annotate - your declaration to add some. For example, the ctn pointer can be a reference to an - object or a whole array (in which case you also has to specify its size). This is done - with the GRAS_ANNOTE call. It is removed from the text passed to the compiler, but it helps - GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an - array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols - being the other fields of the structure). - - Please note that this annotation mechanism is not as robust and cool as this example seems to - imply. If you want to use it yourself, you'd better use the exact right syntax, which is - detailed in the \ref GRAS_dd section. - - \skip GRAS_DEFINE_TYPE - \until matrix_t + 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. \subsection GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c) @@ -515,9 +424,7 @@ \subsection 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. Note the use of the \ref gras_datadesc_by_symbol - function to parse and retrieve the structure declaration which were passed to \ref GRAS_DEFINE_TYPE - above. + 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. @@ -525,14 +432,6 @@ \skip register_messages \until } - \subsection GRAS_ex_mmrpc_matdump 1.e) Helper debugging function (mmrpc_common.c) - - This function dumps a matrix to screen for debugging. - - \skip mat_dump - \until end_of_matrix - \until } - [Back to \ref GRAS_ex_mmrpc_toc] \section GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c) @@ -561,8 +460,8 @@ \subsection GRAS_ex_mmrpc_sermain 2.c) The "main" of the server - This is the "main" of the server. As explained in the \ref - GRAS_main_generation, you must not write any main() + This is the "main" of the server. As explained in the tutorial, \ref + GRAS_tut_tour_setup, 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.