- \ref GRAS_tut_tour_message_recaping_rpc3
- \ref GRAS_tut_tour_message_recaping_rpc4
- \ref GRAS_tut_tour_message_recaping_rpc5
- -
- \ref GRAS_tut_tour_message_recaping_rpc_aside1
- \ref GRAS_tut_tour_message_recaping_rpc_aside2
- \ref GRAS_tut_tour_message_recaping_rpc_aside3
- \ref GRAS_tut_tour_message_recaping_sync
-
+
<hr>
This is the end of the first big part of this tutorial. At this point, you
\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
+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>).
+ 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>).
+ 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>).
+ 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>).
to attach a callback to the message. Of course, you usualy don't want to do
so on every nodes, but only on "servers" or "workers" or such. 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):
+on request incoming 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
If your message is of semantic T3 or T4 (ie, it returns a value to the
caller), then you must use the function gras_msg_rpcreturn() to do so. It
-takes three arguments:
+takes three arguments:
- a timeout to use (so that the server don't get frozen if the client is
unresponsive)
- the message context (the variable ctx of type #gras_msg_cb_ctx_t you got
mallocated in your callback (including the data you returned to the caller:
GRAS made a copy of it during the call to gras_msg_rpcreturn()).
-The callback is expected to return 1 if ok, as detailed in
+The callback is expected to return 0 if ok, as detailed in
\ref GRAS_tut_tour_message_recaping_rpc_aside1.
\subsection GRAS_tut_tour_message_recaping_rpc4 4. Attaching callbacks to the messages
\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. It is
-perfectly valid to register several callbacks to a given message. When a
-message arrives, it is passed to the firstly-registered callback. If the
-callback returns 1 (or any other "true" value), it means that it consumed
-the message, which is discarded. If the callback returns 0, the message is
-passed to the next callback of the stack, and so on. At the end, if no
-callback returned 1, an error message is generated.
+The callback is expected to return 0 if everything went well, which is the
+same semantic than the "main()" function. You can also build stacks of
+callbacks. It is perfectly valid to register several callbacks to a given
+message. When a message arrives, it is passed to the firstly-registered
+callback. If the callback returns 0, it means that it consumed the message,
+which is discarded. If the callback returns 1 (or any other "true" value),
+the message is passed to the next callback of the stack, and so on. At the
+end, if no callback returned 0, an exception is raised.
This mecanism can for example be used to introduce dupplication and replay.
You add a callback simply in charge of storing the message in a database,
-and since it returns 0, the message is then passed to the "real" callback.
+and since it returns 1, the message is then passed to the "real" callback.
To be perfectly honest, I never had use of this functionnality myself, but I
feel it could be useful in some cases...
