+++ /dev/null
-
-/**
-@page GRAS_tut_tour_callbacks Lesson 4: Attaching callbacks to messages
-
-\section GRAS_tut_tour_callbacks_toc Table of Contents
- - \ref GRAS_tut_tour_callbacks_declare
- - \ref GRAS_tut_tour_callbacks_attach
- - \ref GRAS_tut_tour_callbacks_handle
- - \ref GRAS_tut_tour_callback_recap
-
-<hr>
-
-Our program is well and good, but if we had to write a longer program,
-explicitely waiting for messages of a given type would not be really
-practical. To add some more dynamism, what we want to do is to attach
-callbacks to the several messages types, and tell GRAS that we are ready to
-deal with new messages. That's what we will do now.
-
-\section GRAS_tut_tour_callbacks_declare Declaring callbacks
-
-First of all, we define the callback we want to attach to the arrival of the
-"hello" message on the server. Its signature is fixed: it accepts two
-arguments of relative types <tt>gras_msg_cb_ctx_t ctx</tt> and <tt>void
-*</tt>. The first one is a working context we should pass to GRAS when
-speaking about the message we are handling while the second is the payload.
-The callback returns an integer being its error code, just like the "main()"
-function. Here is the actual code of our callback:
-
-\dontinclude 04-callback.c
-\skip gras_msg_cb_ctx_t
-\until end_of_callback
-
-\section GRAS_tut_tour_callbacks_attach Attaching callbacks
-
-Then, we have to change the server code to use this callback instead of
-gras_msg_wait. This simply done by a construct like the following:
-
-\skip cb_register
-\until cb_register
-
-\section GRAS_tut_tour_callbacks_handle Handling incoming messages
-
-Once the callback is declared and attached, the server simply has to call
-\ref gras_msg_handle to tell GRAS it's ready to handle for incoming
-messages. The only argument is the maximum delay we are disposed to wait for
-a message. If the delay is negative, the process will block until a message
-arrives. With delay=0, the process just polls for already arrived messages,
-but do not wait at all if none arrived yet. If the delay is greater than 0,
-the process will wait for at most that amount of seconds. If a message
-arrives in the meanwhile, it won't even wait that long.
-
-Sometimes, you want to handle all messages arriving in a given period
-without really knowing how much messages will come (this is often the case
-during the initialization phase of an algorithm). In that case, use \ref
-gras_msg_handleall . It has the same prototype than \ref gras_msg_handle,
-but waits exactly the passed delay, dealing with all the messages arriving
-in the meanwhile.
-
-We have no such needs in our example, so the code simply reads:
-\skip handle
-\until handle
-
-\section GRAS_tut_tour_callback_recap Recaping everything together
-
-The whole program now reads:
-\include 04-callback.c
-
-And here is the output (unchanged wrt previous version):
-\include 04-callback.output
-
-Our little example turns slowly to a quite advanced GRAS program. It entails
-most of the mecanism most program will use.
-
-There is one last thing you should know about callbacks: you can stack them,
-ie attach several callbacks to the same message. GRAS will pass it to the
-lastly attached first, and if the returned error code is not 0, it will pass
-it also to the next one, and so on. I'm not sure there is any sensible use
-of this feature, but it's possible ;)
-
-Go to \ref GRAS_tut_tour_globals
-*/
