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