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 callbackreturns an integer indicating whether we managed to deal with
  27 the message. I admit that this semantic is a bit troublesome, it should be 0
  28 if we managed to deal properly with the message to mimic "main()" semantic.
  29 That's historical, but I may change this in the future (no worry, I'll add
  30 backward compatibility solutions). Here is the actual code of our callback:
  31
  32 \dontinclude 04-callback.c
  33 \skip gras_msg_cb_ctx_t
  34 \until end_of_callback
  35
  36 \section GRAS_tut_tour_callbacks_attach Attaching callbacks
  37
  38 Then, we have to change the server code to use this callback instead of
  39 gras_msg_wait. This simply done by a construct like the following:
  40
  41 \skip cb_register
  42 \until cb_register
  43
  44 \section GRAS_tut_tour_callbacks_handle Handling incoming messages
  45
  46 Once the callback is declared and attached, the server simply has to call
  47 \ref gras_msg_handle to tell GRAS it's ready to handle for incoming
  48 messages. The only argument is the maximum delay we are disposed to wait for
  49 a message. If the delay is negative, the process will block until a message
  50 arrives. With delay=0, the process just polls for already arrived messages,
  51 but do not wait at all if none arrived yet. If the delay is greater than 0,
  52 the process will wait for at most that amount of seconds. If a message
  53 arrives in the meanwhile, it won't even wait that long.
  54
  55 Sometimes, you want to handle all messages arriving in a given period
  56 without really knowing how much messages will come (this is often the case
  57 during the initialization phase of an algorithm). In that case, use \ref
  58 gras_msg_handleall . It has the same prototype than \ref gras_msg_handle,
  59 but waits exactly the passed delay, dealing with all the messages arriving
  60 in the meanwhile.
  61
  62 We have no such needs in our example, so the code simply reads:
  63 \skip handle
  64 \until handle
  65
  66 \section GRAS_tut_tour_callback_recap Recaping everything together
  67
  68 The whole program now reads:
  69 \include 04-callback.c
  70
  71 And here is the output (unchanged wrt previous version):
  72 \include 04-callback.output
  73
  74 Our little example turns slowly to a quite advanced GRAS program. It entails
  75 most of the mecanism most program will use.
  76
  77 There is one last thing you should know about callbacks: you can stack them,
  78 ie attach several callbacks to the same message. GRAS will pass it to the
  79 lastly attached first, and if the return value is 0, it will pass it also to
  80 the next one, and so on. I'm not sure there is any sensible use of this
  81 feature, but it's possible ;)
  82
  83 Go to \ref GRAS_tut_tour_globals
  84 */