2 @page GRAS_tut_tour_message_recaping Recaping the GRAS messaging system (ongoing)
4 \section GRAS_tut_tour_message_recaping_toc Table of Contents
5 - \ref GRAS_tut_tour_message_recaping_intro
6 - \ref GRAS_tut_tour_message_recaping_rpc
7 - \ref GRAS_tut_tour_message_recaping_rpc1
8 - \ref GRAS_tut_tour_message_recaping_rpc2
9 - \ref GRAS_tut_tour_message_recaping_rpc3
10 - \ref GRAS_tut_tour_message_recaping_rpc4
11 - \ref GRAS_tut_tour_message_recaping_rpc5
12 - \ref GRAS_tut_tour_message_recaping_rpc_aside1
13 - \ref GRAS_tut_tour_message_recaping_rpc_aside2
14 - \ref GRAS_tut_tour_message_recaping_rpc_aside3
15 - \ref GRAS_tut_tour_message_recaping_sync
19 This is the end of the first big part of this tutorial. At this point, you
20 know pretty much everything about message passing in GRAS. In second big
21 part, you will learn how to describe data to the middleware in order to
22 convey your own structures in messages instead of the predefined scalar
23 types. But for now, it is time to recap what we have seen so far.
25 \section GRAS_tut_tour_message_recaping_intro Message passing compared to procedure call
27 In GRAS, you pass message to get remote component to achieve some work for
28 you. In some sense, this is very similar to the good old procedure
29 abstraction: you call some procedure to get <i>it</i> doing some work for
30 you. Looking closer at this good old abstraction, we notice 4 call semantics:
32 - <tt>void procedure(void)</tt> this is a procedure accepting no argument
33 and returning no result (<b>type 1</b>).
34 - <tt>void procedure2(int i)</tt> this is a procedure accepting an
35 argument, but returning no result (<b>type 2</b>).
36 - <tt>int function(void)</tt> this is a function accepting no argument, but
37 returning a result (<b>type 3</b>).
38 - <tt>int function(int i)</tt> this is a function accepting an argument,
39 and returning a result (<b>type 4</b>).
41 The whole story of the GRAS message passing subsystem is to allow to
42 reproduce these call semantics in a distributed setting. That being said, We
43 must also note that some messages exchanged using GRAS do not intend to
44 mimic these semantics, but instead to help the syncronisation between
45 distributed processes. When exchanged from peer A to peer B, they don't mean
46 that A requests a service from B, but rather that A gives an information (a
47 signal) to B. It could be for example that A reached a specific point of its
48 computation, and that B can proceed with its own (this syncronisation schema
49 being a simple rendez-vous). These messages are covered in the next part of
50 this recapping (\ref GRAS_tut_tour_message_recaping_sync).
52 To return on the call semantics described above, there is a big difference
53 between the types T1 and T2 on one side and the types T3 and T4 on the other
54 side. In the second case, the caller do wait for an answer from the callee
55 side. In a distributed setting, you have to exchange one extra message in
56 that case. That is why T1;T2 (sometimes refered as <i>one-way messages</i>)
57 are treated quite differently in GRAS from T3;T4.
59 \section GRAS_tut_tour_message_recaping_rpc Remote Procedure Call in GRAS
61 Mimicing the same call semantic in a distributed setting is the goal of the
62 RPC systems. To do so in GRAS, you must do the following actions:
64 \subsection GRAS_tut_tour_message_recaping_rpc1 1. Declaring a datatype
66 If you want that your messages convey complex datatypes and not only scalar,
67 you have to do it first. Learning how to do so is the subject of the second
68 part of this tutorial. For now, simply observe that this is the same thing
69 than doing a <tt>typedef</tt> in your code before using this type:
70 \verbatim typedef struct {
73 } *mytype;\endverbatim
75 \subsection GRAS_tut_tour_message_recaping_rpc2 2. Declaring a message type
77 This is very similar to forward procedure declarations in your sequential
79 \verbatim int myfunction(mytype myarg);\endverbatim
80 More formally it comes down to associating a data type to a given
81 symbol name. For example, in \ref GRAS_tut_tour_simpledata, we specified
82 that the message <tt>"kill"</tt> conveyed a double as payload.
84 Doing so depends on whether you have a one-way message (ie, type 1 or 2) or
85 not. One-way messages are declared with gras_msgtype_declare() while RPC
86 messages are declared with gras_msgtype_declare_rpc()
88 \subsection GRAS_tut_tour_message_recaping_rpc3 3. Declaring message callbacks
90 If the message is intended to be a work request one (and not a
91 syncronization one as detailed below), you then want to attach some code to
92 execute when a process receives the given request. In other words, you want
93 to attach a callback to the message. Of course, you usualy don't want to do
94 so on every nodes, but only on "servers" or "workers" or such. First of all,
95 you need to declare the callback itself. This function that will be executed
96 on request incomming must follow a very specific prototype (the same
97 regardless of the call semantic):
100 int callback_name(gras_msg_cb_ctx_t context, void *payload) \endverbatim
102 The first argument (of type #gras_msg_cb_ctx_t) is an opaque structure
103 describing the callback context: who sent you the message (which you can
104 find back using gras_msg_cb_ctx_from()), whether it's a one-way call or not,
105 and so on. GRAS functions altering the call (such as gras_msg_rpcreturn(),
106 used to return the result to the caller) require this context as argument.
108 The second argument is a pointer to where the message payload is stored. In
109 the T1 and T3 semantics (ie, when the message had no payload), this second
110 argument is NULL. If not, the first line of your callback will probably
111 retrieve the payload and store it in a variable of yours. The semantic for
112 this is very systematic, if not elegant: If your payload is of type TOTO,
113 <tt>payload</tt> is a pointer to a TOTO variable. So, cast it properly (add
114 <tt>(TOTO*)</tt> in front of it), and dereference it (add a star right
115 before the cast). For example:
118 TOTO myvariable = *(TOTO*) payload; \endverbatim
120 This becomes even uglier if the conveyed type is a pointer itself, but you
121 must stick to the rule anyway:
124 int **myvariable = *(int ** *) payload; \endverbatim
126 If your message is of semantic T3 or T4 (ie, it returns a value to the
127 caller), then you must use the function gras_msg_rpcreturn() to do so. It
128 takes three arguments:
129 - a timeout to use (so that the server don't get frozen if the client is
131 - the message context (the variable ctx of type #gras_msg_cb_ctx_t you got
132 as argument of the callback)
133 - a pointer to the data to send back.
134 After it returned the result this way, you should free any data you
135 mallocated in your callback (including the data you returned to the caller:
136 GRAS made a copy of it during the call to gras_msg_rpcreturn()).
138 The callback is expected to return 0 if ok, as detailed in
139 \ref GRAS_tut_tour_message_recaping_rpc_aside1.
141 \subsection GRAS_tut_tour_message_recaping_rpc4 4. Attaching callbacks to the messages
143 To attach a given callback to a given message, you simply use
144 gras_cb_register(). If you even want to de-register a callback, use
145 gras_cb_unregister().
147 \subsection GRAS_tut_tour_message_recaping_rpc5 5. Send your message from the client
149 Again, sending messages depend on the semantic call. If you have a one-way
150 message, you should call gras_msg_send() while RPC calls are sent with
151 gras_msg_rpccall(). The main difference between them is that you have an
152 extra argument for RPC, to specify where to store the result.
154 It is also possible to call RPC asyncronously: you send the request (using
155 gras_msg_rpc_async_call()), do some other computation. And then later, you
156 wait for the answer of your RPC (using gras_msg_rpc_async_wait()).
158 \subsection GRAS_tut_tour_message_recaping_rpc_aside1 Aside: stacking callbacks
160 The callback is expected to return 0 if everything went well, which is the
161 same semantic than the "main()" function. You can also build stacks of
162 callbacks. It is perfectly valid to register several callbacks to a given
163 message. When a message arrives, it is passed to the firstly-registered
164 callback. If the callback returns 0, it means that it consumed the message,
165 which is discarded. If the callback returns 1 (or any other "true" value),
166 the message is passed to the next callback of the stack, and so on. At the
167 end, if no callback returned 0, an exception is raised.
169 This mecanism can for example be used to introduce dupplication and replay.
170 You add a callback simply in charge of storing the message in a database,
171 and since it returns 1, the message is then passed to the "real" callback.
172 To be perfectly honest, I never had use of this functionnality myself, but I
173 feel it could be useful in some cases...
175 \subsection GRAS_tut_tour_message_recaping_rpc_aside2 Aside: Exceptions and callbacks
177 One of the parts I'm the most proud of in GRAS is this one: imagine you have
178 a rpc callback executing on a remote server. If this callback raises an
179 exception, it will be propagated on the network back to the client, and
180 revived there. So, the client will get automatically any exception raised by
181 the server. Cool, isn't it? Afterward, simply refer to the <tt>host</tt>
182 field of the #xbt_ex_t to retrieve the machine on which it was initialy
185 In case you wonder about the exceptions I'm speaking about (after all,
186 SimGrid is in C ANSI, and there is usually no exception mecanism in C ANSI),
187 you may want to refer to the section \ref XBT_ex. Note that exception can be
188 troublesome to use (mainly because the compiler won't catch your mistakes on
191 \subsection GRAS_tut_tour_message_recaping_rpc_aside3 Aside: Symbol versionning (TODO)
193 This section covers a point not explicited elsewhere in the documentation.
194 It may be seen as a bit hardcore, and you should probably skip it the first
195 time you read the tutorial.
197 \section GRAS_tut_tour_message_recaping_sync Syncronization messages in GRAS (TODO)
