doc/gtut-tour-07-timers.doc

   1 /**
   2 @page GRAS_tut_tour_timers Lesson 7: Using internal timers
   3
   4 \section GRAS_tut_tour_timers_toc Table of Contents
   5  - \ref GRAS_tut_tour_timers_intro
   6  - \ref GRAS_tut_tour_timers_use
   7  - \ref GRAS_tut_tour_timers_recap
   8
   9 <hr>
  10
  11 \section GRAS_tut_tour_timers_intro Introduction
  12
  13 The messaging primitives we saw until now allow the processes to react to
  14 external events. This is good, but sometimes, you want the same action to be
  15 done periodically. Think of a system based on a group of processes. If you
  16 want to give some adaptability to this system, you shouldn't hardcode the
  17 memberships but have the members send a message to a coordinator to register
  18 to the system.
  19
  20 This add some dynamism to your system since new members can join at any
  21 time. To have a process leaving the system, you can imagine an "unregister"
  22 message symetric to the "register" one. But how will you deal with failures?
  23 What if a process leaves without being given the ability to inform the
  24 coordinator?
  25
  26 One solution is to have the members re-register periodically, so that the
  27 coordinator can detect the processes which didn't do so since a while, and
  28 dismiss them.
  29
  30 To implement this in GRAS, we need some more functions: gras_timer_repeat()
  31 allows to specify a periodic action and gras_timer_delay() allows to get an
  32 action done once a given delay expires. gras_timer_cancel_delay() and
  33 gras_timer_cancel_repeat() allow to remove already declared timers. Actions
  34 must be function without argument nor result (<tt>void my_action(void){
  35 ... }</tt>).
  36
  37 It is important to note that timers are not prehemptive. They will not start
  38 as soon as they are ready. Instead, they get served when you go into
  39 gras_msg_handle() (and they are served before incoming messages). This is
  40 because allowing timers to run in parallel to the callbacks would add
  41 parallelism to the user code, which would have to protect data with mutexes.
  42 This is a level of complexity I really don't want for user code. If you
  43 really need several running entities, simply run several processes (see \ref
  44 GRAS_tut_intro_model for more details).
  45
  46 \section GRAS_tut_tour_timers_use Putting timers into action
  47
  48 We will change the client of our example so that it send an hello message
  49 every half second to the server. Then we will add a delayed action scheduled
  50 5 seconds later in charge of stopping every processes. For this to work, we
  51 first need to add a global to the server too, containing the socket binded
  52 onto the server (to send messages) and a boolean indicating whether we are
  53 done or not, just like we did on the server side in \ref
  54 GRAS_tut_tour_globals. Here is the resulting global structure:
  55 \dontinclude 07-timers.c
  56 \skip client_data
  57 \until client_data_t
  58
  59 Then, we define the repetitive action in charge of sending messages to the
  60 server:
  61
  62 \skip client_do_hello
  63 \until end_of_client_do_hello
  64
  65 This timer is installed the following way. You simply tell the action to
  66 schedule and its periodicity.
  67 \skip gras_timer_repeat
  68 \until gras_timer_repeat
  69
  70 Desinstalling this is not harder. You tell the action to unschedule, and the
  71 periodicity at which it was desinstalled (so that the same action can be
  72 scheduled at different intervals, and each of them be desinstallable
  73 separately).
  74 \dontinclude 07-timers.c
  75 \skip gras_timer_cancel_repeat
  76 \until gras_timer_cancel_repeat
  77
  78 Then comes the delayed action in charge of stopping everything, which should
  79 be self-explanatory at this point. It could be cancelled before its
  80 expiration using gras_timer_cancel_delay(), which accepts exactly the same
  81 kind of arguments than gras_timer_cancel_repeat().
  82 \dontinclude 07-timers.c
  83 \skip client_do_stop
  84 \until end_of_client_do_stop
  85
  86 Finally, we should change the client main function to adapt to these
  87 modifications, as you can see in the recapping below.
  88
  89 \section GRAS_tut_tour_timers_recap Recapping everything together
  90
  91 The program now reads:
  92 \include 07-timers.c
  93
  94 Which produces the expected output:
  95 \include 07-timers.output
  96
  97 Go to \ref GRAS_tut_tour_exceptions
  98
  99 */