statusd.tex

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