doc/gtut-tour-recap-messages.doc

   1 /**
   2 @page GRAS_tut_tour_message_recaping Lesson 11: Recaping the GRAS messaging system (TODO)
   3
   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_rpc_aside1
  12  - \ref GRAS_tut_tour_message_recaping_sync
  13
  14 <hr>
  15
  16 This is the end of the first big part of this tutorial. At this point, you
  17 know pretty much everything about message passing in GRAS. In second big
  18 part, you will learn how to describe data to the middleware, in order to
  19 convey your own structures in messages instead of the predefined scalar
  20 types. But for now, it is time to recap what we have seen so far.
  21
  22 \section GRAS_tut_tour_message_recaping_intro Message passing compared to procedure call
  23
  24 In GRAS, you pass message to get remote component to achieve some work for
  25 you. In some sense, this is very similar to the good old procedure
  26 abstraction: you call some procedure to get <i>it</i> doing some work for
  27 you. Looking closer at this good old abstraction, we notice 4 call semantics:
  28
  29  - <tt>void procedure(void)</tt> this is a procedure accepting no argument
  30    and returning no result (<b>type 1</b>).
  31  - <tt>void procedure2(int i)</tt> this is a procedure accepting an
  32    argument, but returning no result (<b>type 2</b>).
  33  - <tt>int function(void)</tt> this is a function accepting no argument, but
  34    returning a result (<b>type 3</b>).
  35  - <tt>int function(int i)</tt> this is a function accepting an argument,
  36    and returning a result (<b>type 4</b>).
  37
  38 The whole story of the GRAS message passing subsystem is to allow to
  39 reproduce these call semantics in a distributed setting. That being said, We
  40 must also note that some messages exchanged using GRAS do not intend to
  41 mimic these semantics, but instead to help the syncronisation between
  42 distributed processes. When exchanged from peer A to peer B, they don't mean
  43 that A requests a service from B, but rather that A gives an information, a
  44 signal, to B. It could be for example that A reached a specific point of its
  45 computation, and that B can proceed with its own (this syncronisation schema
  46 being a simple rendez-vous).
  47
  48 In the call semantics described above, there is a big difference between the
  49 types T1 and T2 on one side and the types T3 and T4 on the other side. In
  50 the second case, the caller do wait for an answer from the callee side. In a
  51 distributed setting, you have to exchange one extra message in that case.
  52 That is why T1;T2 (sometimes refered as <i>one-way messages</i>) are treated
  53 quite differently in GRAS from T3;T4.
  54
  55 \section GRAS_tut_tour_message_recaping_rpc Remote Procedure Call in GRAS
  56
  57 Mimicing the same call semantic in a distributed setting is the goal of the
  58 RPC systems. To do so in GRAS, you must do the following actions:
  59
  60 \subsection GRAS_tut_tour_message_recaping_rpc1 1. Declaring a datatype
  61
  62 If you want that your messages convey complex datatypes and not only scalar,
  63 you have to do it first. Learning how to do so is the subject of the second
  64 part of this tutorial. For now, simply observe that this is the same thing
  65 than doing a <tt>typedef</tt> in your code before using this type.
  66
  67 \subsection GRAS_tut_tour_message_recaping_rpc2 2. Declaring a message type
  68
  69 This is very similar to forward procedure declarations in your sequential
  70 code. More formally it comes down to associating a data type to a given
  71 symbol name. For example, in \ref GRAS_tut_tour_simpledata, we specified
  72 that the message <tt>"kill"</tt> conveyed a double as payload.
  73
  74 Doing so depends on whether you have a one-way message (ie, type 1 or 2) or
  75 not. One-way messages are declared with gras_msgtype_declare() while RPC
  76 messages are declared with gras_msgtype_declare_rpc()
  77
  78 \subsection GRAS_tut_tour_message_recaping_rpc3 3. Attach some code to the message
  79
  80 If the message is intended to be a work request one (and not a
  81 syncronization one as detailed below), you then want to attach some code to
  82 execute when a process receives the given request. In other words, you want
  83 to attach a callback to the message. First of all, you need to declare the
  84 callback itself. This function that will be executed on request incomming
  85 must follow a very specific prototype (the same regardless of the call
  86 semantic):
  87
  88 \verbatim
  89 int callback_name(gras_msg_cb_ctx_t context, void *payload) \endverbatim
  90
  91 The first argument (of type #gras_msg_cb_ctx_t) is an opaque structure
  92 describing the callback context: who sent you the message (which you can
  93 find back using gras_msg_cb_ctx_from()), whether it's a one-way call or not,
  94 and so on. GRAS functions altering the call (such as gras_msg_rpcreturn(),
  95 used to return the result to the caller) require this context as argument.
  96
  97 The second argument is a pointer to where the message payload is stored. In
  98 the T1 and T3 semantics (ie, when the message had no payload), this second
  99 argument is NULL. If not, the first line of your callback will probably
 100 retrieve the payload and store it in a variable of yours. The semantic for
 101 this is very systematic, if not elegant: If your payload is of type TOTO,
 102 <tt>payload</tt> is a pointer to a TOTO variable. So, cast it properly (add
 103 <tt>(TOTO*)</tt> in front of it), and dereference it (add a star right
 104 before the cast). For example:
 105
 106 \verbatim
 107 TOTO myvariable = *(TOTO*) payload; \endverbatim
 108
 109 This becomes even uglier if the conveyed type is a pointer itself, but you
 110 must stick to the rule anyway:
 111
 112 \verbatim
 113 int **myvariable = *(int ** *) payload; \endverbatim
 114
 115 The callback is expected to return 1 if ok, as detailed in
 116 \ref GRAS_tut_tour_message_recaping_rpc_aside1.
 117
 118
 119
 120 \subsection GRAS_tut_tour_message_recaping_rpc_aside1 Aside: stacking callbacks
 121
 122 The callback is expected to return 1 if it consumed the message properly.
 123 This semantic may be troublesome since it really differs from the one used
 124 in the main() function, but this allows to build callback stacks.
 125
 126
 127 \section GRAS_tut_tour_message_recaping_sync Syncronization messages in GRAS
 128
 129
 130 */
 131