From: mquinson Date: Mon, 6 Nov 2006 16:34:16 +0000 (+0000) Subject: Begin a recaping of hte first part of the tutorial X-Git-Tag: v3.3~2448 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/4dbb8291093865792122981a1403852581d8b91f Begin a recaping of hte first part of the tutorial git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@2911 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- diff --git a/doc/gtut-tour-recap-messages.doc b/doc/gtut-tour-recap-messages.doc new file mode 100644 index 0000000000..2172b5d175 --- /dev/null +++ b/doc/gtut-tour-recap-messages.doc @@ -0,0 +1,131 @@ +/** +@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 + +
+ +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 it doing some work for +you. Looking closer at this good old abstraction, we notice 4 call semantics: + + - void procedure(void) this is a procedure accepting no argument + and returning no result (type 1). + - void procedure2(int i) this is a procedure accepting an + argument, but returning no result (type 2). + - int function(void) this is a function accepting no argument, but + returning a result (type 3). + - int function(int i) this is a function accepting an argument, + and returning a result (type 4). + +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 one-way messages) 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 typedef 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 "kill" 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, +payload is a pointer to a TOTO variable. So, cast it properly (add +(TOTO*) 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 + + +*/ +