doc/gtut-tour-04-callback.doc

   1
   2 /**
   3 @page GRAS_tut_tour_callbacks Lesson 4: Attaching callbacks to messages
   4
   5 \section GRAS_tut_tour_callbacks_toc Table of Contents
   6  - \ref GRAS_tut_tour_callbacks_declare
   7  - \ref GRAS_tut_tour_callbacks_attach
   8  - \ref GRAS_tut_tour_callbacks_handle
   9  - \ref GRAS_tut_tour_callback_recap
  10
  11 <hr>
  12
  13 Our program is well and good, but if we had to write a longer program,
  14 explicitely waiting for messages of a given type would not be really
  15 practical. To add some more dynamism, what we want to do is to attach
  16 callbacks to the several messages types, and tell GRAS that we are ready to
  17 deal with new messages. That's what we will do now.
  18
  19 \section GRAS_tut_tour_callbacks_declare Declaring callbacks
  20
  21 First of all, we define the callback we want to attach to the arrival of the
  22 "hello" message on the server. Its signature is fixed: it accepts two
  23 arguments of relative types <tt>gras_msg_cb_ctx_t ctx</tt> and <tt>void
  24 *</tt>. The first one is a working context we should pass to GRAS when
  25 speaking about the message we are handling while the second is the payload.
  26 The callback returns an integer being its error code, just like the "main()"
  27 function. Here is the actual code of our callback:
  28
  29 \dontinclude 04-callback.c
  30 \skip gras_msg_cb_ctx_t
  31 \until end_of_callback
  32
  33 \section GRAS_tut_tour_callbacks_attach Attaching callbacks
  34
  35 Then, we have to change the server code to use this callback instead of
  36 gras_msg_wait. This simply done by a construct like the following:
  37
  38 \skip cb_register
  39 \until cb_register
  40
  41 \section GRAS_tut_tour_callbacks_handle Handling incoming messages
  42
  43 Once the callback is declared and attached, the server simply has to call
  44 \ref gras_msg_handle to tell GRAS it's ready to handle for incoming
  45 messages. The only argument is the maximum delay we are disposed to wait for
  46 a message. If the delay is negative, the process will block until a message
  47 arrives. With delay=0, the process just polls for already arrived messages,
  48 but do not wait at all if none arrived yet. If the delay is greater than 0,
  49 the process will wait for at most that amount of seconds. If a message
  50 arrives in the meanwhile, it won't even wait that long.
  51
  52 Sometimes, you want to handle all messages arriving in a given period
  53 without really knowing how much messages will come (this is often the case
  54 during the initialization phase of an algorithm). In that case, use \ref
  55 gras_msg_handleall . It has the same prototype than \ref gras_msg_handle,
  56 but waits exactly the passed delay, dealing with all the messages arriving
  57 in the meanwhile.
  58
  59 We have no such needs in our example, so the code simply reads:
  60 \skip handle
  61 \until handle
  62
  63 \section GRAS_tut_tour_callback_recap Recaping everything together
  64
  65 The whole program now reads:
  66 \include 04-callback.c
  67
  68 And here is the output (unchanged wrt previous version):
  69 \include 04-callback.output
  70
  71 Our little example turns slowly to a quite advanced GRAS program. It entails
  72 most of the mecanism most program will use.
  73
  74 There is one last thing you should know about callbacks: you can stack them,
  75 ie attach several callbacks to the same message. GRAS will pass it to the
  76 lastly attached first, and if the returned error code is not 0, it will pass
  77 it also to the next one, and so on. I'm not sure there is any sensible use
  78 of this feature, but it's possible ;)
  79
  80 Go to \ref GRAS_tut_tour_globals
  81 */