--- /dev/null
+/**
+@page GRAS_tut_tour_message_recaping Lesson 11: Recaping the GRAS messaging system (TODO)
+
+\section GRAS_tut_tour_message_recaping_toc Table of Contents
+ - \ref GRAS_tut_tour_message_recaping_intro
+ - \ref GRAS_tut_tour_message_recaping_rpc
+ - \ref GRAS_tut_tour_message_recaping_rpc1
+ - \ref GRAS_tut_tour_message_recaping_rpc2
+ - \ref GRAS_tut_tour_message_recaping_rpc3
+ - \ref GRAS_tut_tour_message_recaping_rpc4
+ - \ref GRAS_tut_tour_message_recaping_rpc_aside1
+ - \ref GRAS_tut_tour_message_recaping_sync
+
+<hr>
+
+This is the end of the first big part of this tutorial. At this point, you
+know pretty much everything about message passing in GRAS. In second big
+part, you will learn how to describe data to the middleware, in order to
+convey your own structures in messages instead of the predefined scalar
+types. But for now, it is time to recap what we have seen so far.
+
+\section GRAS_tut_tour_message_recaping_intro Message passing compared to procedure call
+
+In GRAS, you pass message to get remote component to achieve some work for
+you. In some sense, this is very similar to the good old procedure
+abstraction: you call some procedure to get <i>it</i> doing some work for
+you. Looking closer at this good old abstraction, we notice 4 call semantics:
+
+ - <tt>void procedure(void)</tt> this is a procedure accepting no argument
+ and returning no result (<b>type 1</b>).
+ - <tt>void procedure2(int i)</tt> this is a procedure accepting an
+ argument, but returning no result (<b>type 2</b>).
+ - <tt>int function(void)</tt> this is a function accepting no argument, but
+ returning a result (<b>type 3</b>).
+ - <tt>int function(int i)</tt> this is a function accepting an argument,
+ and returning a result (<b>type 4</b>).
+
+The whole story of the GRAS message passing subsystem is to allow to
+reproduce these call semantics in a distributed setting. That being said, We
+must also note that some messages exchanged using GRAS do not intend to
+mimic these semantics, but instead to help the syncronisation between
+distributed processes. When exchanged from peer A to peer B, they don't mean
+that A requests a service from B, but rather that A gives an information, a
+signal, to B. It could be for example that A reached a specific point of its
+computation, and that B can proceed with its own (this syncronisation schema
+being a simple rendez-vous).
+
+In the call semantics described above, there is a big difference between the
+types T1 and T2 on one side and the types T3 and T4 on the other side. In
+the second case, the caller do wait for an answer from the callee side. In a
+distributed setting, you have to exchange one extra message in that case.
+That is why T1;T2 (sometimes refered as <i>one-way messages</i>) are treated
+quite differently in GRAS from T3;T4.
+
+\section GRAS_tut_tour_message_recaping_rpc Remote Procedure Call in GRAS
+
+Mimicing the same call semantic in a distributed setting is the goal of the
+RPC systems. To do so in GRAS, you must do the following actions:
+
+\subsection GRAS_tut_tour_message_recaping_rpc1 1. Declaring a datatype
+
+If you want that your messages convey complex datatypes and not only scalar,
+you have to do it first. Learning how to do so is the subject of the second
+part of this tutorial. For now, simply observe that this is the same thing
+than doing a <tt>typedef</tt> in your code before using this type.
+
+\subsection GRAS_tut_tour_message_recaping_rpc2 2. Declaring a message type
+
+This is very similar to forward procedure declarations in your sequential
+code. More formally it comes down to associating a data type to a given
+symbol name. For example, in \ref GRAS_tut_tour_simpledata, we specified
+that the message <tt>"kill"</tt> conveyed a double as payload.
+
+Doing so depends on whether you have a one-way message (ie, type 1 or 2) or
+not. One-way messages are declared with gras_msgtype_declare() while RPC
+messages are declared with gras_msgtype_declare_rpc()
+
+\subsection GRAS_tut_tour_message_recaping_rpc3 3. Attach some code to the message
+
+If the message is intended to be a work request one (and not a
+syncronization one as detailed below), you then want to attach some code to
+execute when a process receives the given request. In other words, you want
+to attach a callback to the message. First of all, you need to declare the
+callback itself. This function that will be executed on request incomming
+must follow a very specific prototype (the same regardless of the call
+semantic):
+
+\verbatim
+int callback_name(gras_msg_cb_ctx_t context, void *payload) \endverbatim
+
+The first argument (of type #gras_msg_cb_ctx_t) is an opaque structure
+describing the callback context: who sent you the message (which you can
+find back using gras_msg_cb_ctx_from()), whether it's a one-way call or not,
+and so on. GRAS functions altering the call (such as gras_msg_rpcreturn(),
+used to return the result to the caller) require this context as argument.
+
+The second argument is a pointer to where the message payload is stored. In
+the T1 and T3 semantics (ie, when the message had no payload), this second
+argument is NULL. If not, the first line of your callback will probably
+retrieve the payload and store it in a variable of yours. The semantic for
+this is very systematic, if not elegant: If your payload is of type TOTO,
+<tt>payload</tt> is a pointer to a TOTO variable. So, cast it properly (add
+<tt>(TOTO*)</tt> in front of it), and dereference it (add a star right
+before the cast). For example:
+
+\verbatim
+TOTO myvariable = *(TOTO*) payload; \endverbatim
+
+This becomes even uglier if the conveyed type is a pointer itself, but you
+must stick to the rule anyway:
+
+\verbatim
+int **myvariable = *(int ** *) payload; \endverbatim
+
+The callback is expected to return 1 if ok, as detailed in
+\ref GRAS_tut_tour_message_recaping_rpc_aside1.
+
+
+
+\subsection GRAS_tut_tour_message_recaping_rpc_aside1 Aside: stacking callbacks
+
+The callback is expected to return 1 if it consumed the message properly.
+This semantic may be troublesome since it really differs from the one used
+in the main() function, but this allows to build callback stacks.
+
+
+\section GRAS_tut_tour_message_recaping_sync Syncronization messages in GRAS
+
+
+*/
+
