statusd.tex

   1
   2 \section{Writing \command{ion-statusd} monitors}
   3
   4 All statusbar meters that do not monitor the internal state of Ion should
   5 go in the separate \command{ion-statusd} program.
   6
   7 Whenever the user requests a meter \code{\%foo} or \code{\%foo_bar} to be
   8 inserted in a statusbar, \file{mod\_statusbar} asks \command{ion-statusd} to
   9 load \fnref{statusd_foo.lua} on its search path (same as that for Ion-side
  10 scripts). This script should then supply all meters with the initial part
  11 '\code{foo}'.
  12
  13 To provide this value, the script should simply call \code{statusd.inform}
  14 with the name of the meter and the value as a string.
  15 Additionally the script should provide a 'template' for the meter to
  16 facilitate expected width calculation by \file{mod\_statusbar}, and
  17 may provide a 'hint' for colour-coding the value. The interpretation
  18 of hints depends on the graphical style in use, and currently the
  19 stock styles support the \code{normal}, \code{important} and
  20 \code{critical} hints.
  21
  22
  23 In our example of the 'foo monitor', at script init we might broadcast
  24 the template as follows:
  25
  26 \begin{verbatim}
  27 statusd.inform("foo_template", "000")
  28 \end{verbatim}
  29
  30 To inform \file{mod\_statusbar} of the actual value of the meter and
  31 indicate that the value is critical if above 100, we might write the
  32 following function:
  33
  34 \begin{verbatim}
  35 local function inform_foo(foo)
  36     statusd.inform("foo", tostring(foo))
  37     if foo>100 then
  38         statusd.inform("foo_hint", "critical")
  39     else
  40         statusd.inform("foo_hint", "normal")
  41     end
  42 end
  43 \end{verbatim}
  44
  45 To periodically update the value of the meter, we must use timers.
  46 First we must create one:
  47
  48 \begin{verbatim}
  49 local foo_timer=statusd.create_timer()
  50 \end{verbatim}
  51
  52 Then we write a function to be called whenever the timer expires.
  53 This function must also restart the timer.
  54
  55 \begin{verbatim}
  56 local function update_foo()
  57     local foo= ... measure foo somehow ...
  58     inform_foo(foo)
  59     foo_timer:set(settings.update_interval, update_foo)
  60 end
  61 \end{verbatim}
  62
  63 Finally, at the end of our script we want to do the initial
  64 measurement, and set up timer for further measurements:
  65
  66 \begin{verbatim}
  67 update_foo()
  68 \end{verbatim}
  69
  70
  71 If our scripts supports configurable parameters, the following code
  72 (at the beginning of the script) will allow them to be configured in
  73 \file{cfg\_statusbar.lua} and passed to the status daemon and our script:
  74
  75 \begin{verbatim}
  76 local defaults={
  77     update_interval=10*1000, -- 10 seconds
  78 }
  79
  80 local settings=table.join(statusd.get_config("foo"), defaults)
  81 \end{verbatim}