doc/gtut-tour-7-timers.doc

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