#####################################################################
/** \addtogroup GRAS_API
-
- \section GRAS_funct Offered functionnalities
+
+\htmlonly
+<div class="toc">
+<div class="tocTitle">Table of content</div>
+<ol type="1">
+<li> <a href="#GRAS_funct">API documentation</a>
+<li> <a href="#GRAS_example">Examples</a>
+<li> <a href="#GRAS_tut_presentation">Tutorial</a>
+<li> <a href="#GRAS_howto_presentation">HOWTOs</a>
+</div>
+\endhtmlonly
+
+ \section GRAS_funct API documentation
+ GRAS offers the following functionnalities
- <b>\ref GRAS_comm</b>: 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
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).
- - <b>\ref GRAS_code</b>: 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
- \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
/** @} */
-#####################################################################
-/** @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 <!--
- DOXYGEN_NAVBAR_LABEL="Project management"
- DOXYGEN_NAVBAR_CHILD "main() and GRAS"=GRAS_main_generation.html
- DOXYGEN_NAVBAR_CHILD "Compiling your GRAS project"=GRAS_compile.html
- --> \endhtmlonly
-*/
-
#####################################################################
/** @addtogroup GRAS_ex
- \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 <!--
DOXYGEN_NAVBAR_CHILD "Ping-Pong"=GRAS_ex_ping.html
DOXYGEN_NAVBAR_CHILD "RPC"=GRAS_ex_mmrpc.html
<tt>examples/gras</tt>.
*/
-#####################################################################
-######################### 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
-
- <hr>
-
- \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 <tt>main</tt> 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
- <tt>make install</tt> (the source resides in the tools/gras/ directory).
- Here is the calling syntax:
- \verbatim gras_stub_generator <project_name> <deployment_file.xml>\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 <tt>_<project_name>_<process_kind>.c</tt> 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 <tt>_<project_name>_simulator.c</tt> 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
-
- <hr>
-
- \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 #################################
#####################################################################
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. 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
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
\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.
\section GRAS_ex_stoken_deploy 1) Deployment file
Here is the deployment file:
- \include examples/gras/tokenS/tokenS_deployment.xml
+ \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
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/tokenS/tokenS.c
+ \dontinclude examples/gras/mutual_exclusion/simple_token/simple_token.c
\skip typedef
\until }
the server's answer.
This example resides in the <b>examples/gras/mmrpc/mmrpc.c</b> 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
- \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
\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 <i>annotate</i>
- 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)
\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.
\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)
\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.
