x2/README.md

   1 Usage
   2 -----
   3
   4 ### Build
   5
   6 `make build`
   7
   8 ### Install
   9
  10 To copy everything from `./bin` to `$HOME/bin`:
  11
  12 `make install`
  13
  14 ### Use
  15
  16 In my `~/.xinitrc` I have something like the following:
  17
  18 ```sh
  19 ( $BIN/khatus \
  20     --wifi_interface      'wlp3s0' \
  21     --interval_bluetooth  5 \
  22     --interval_net_wifi   5 \
  23     --interval_disk_space 5 \
  24 | stdbuf -o L tee \
  25     >(stdbuf -o L "$BIN"/khatus_bar \
  26         -v Opt_Mpd_Song_Max_Chars=10 \
  27         -v Opt_Pulseaudio_Sink=0 \
  28         -v GC_Interval=1800 \
  29         -f <("$BIN"/khatus_gen_bar_make_status \
  30                 -v Status_Fmt=' E=%s%% M=%d%% P=[%s %sr %sd %st %si %sz] C=[%s %s°C %srpm] D=[%s%% %s▲ %s▼] W=[%s %s▲ %s▼] B=%s *=%s%% (%s) [%s] %s°F %s ' \
  31                 -v Status_Args='@energy_percent,@memory_percent,@processes_count_all,@processes_count_r,@processes_count_d,@processes_count_t,@processes_count_i,@processes_count_z,@cpu_loadavg,@cpu_temp,@cpu_fan_speed,@disk_space,@disk_io_w,@disk_io_r,@net_wifi:wlp3s0,@net_io_w:wlp3s0,@net_io_r:wlp3s0,@bluetooth_power,@backlight_percent,@volume_pa_device:0,@mpd,@weather_temp_f,@datetime' \
  32             ) \
  33     | "$BIN"/khatus_actuate_status_bar_to_xsetroot_name \
  34     ) \
  35     >(stdbuf -o L "$BIN"/khatus_monitor_energy \
  36     | "$BIN"/khatus_actuate_alert_to_notify_send \
  37     ) \
  38     >(stdbuf -o L "$BIN"/khatus_monitor_errors \
  39     | "$BIN"/khatus_actuate_alert_to_notify_send \
  40     ) \
  41     >(stdbuf -o L "$BIN"/khatus_monitor_devices \
  42     | "$BIN"/khatus_actuate_alert_to_notify_send \
  43     ) \
  44     >(stdbuf -o L "$BIN"/khatus_actuate_device_add_to_automount \
  45     | "$BIN"/khatus_actuate_alert_to_notify_send \
  46     ) \
  47 ) \
  48 2> >($BIN/twrap >> $KHATUS_LOGS_DIR/main.log) \
  49 1> /dev/null \
  50 &
  51 ```
  52 (where `twrap` is a simple script which prefixes a timestamp to each line)
  53
  54 The idea is to support appending any number of ad-hoc, experimental monitors by
  55 giving maximum flexibility for what to do with the sensor outputs, while
  56 maintaining some uniformity of msg formats (again, to ease ad-hoc combinations
  57 (e.g. Does the CPU get hotter when MPD is playing Wu-Tang?)).  `khatus_bar`,
  58 `khatus_monitor_energy` and `khatus_monitor_errors` are just some initial
  59 examples.
  60
  61 Design
  62 ------
  63
  64 ### 2.0
  65
  66 In an effort to simplify the components and their interfaces, I removed the
  67 concept of a global controller from the previous design (which, at least for
  68 now, is superfluous), so now it is essentially a pub-sub - parallel publishers
  69 (sensors) write to a pipe, which is then copied to any number of interested
  70 subscribers that can filter-out what they need and then do whatever they want
  71 with the data. Status bar is one such subscriber:
  72
  73 `P1 > pipe&; P2 > pipe&; ... PN > pipe&; tail -f pipe | tee >(S1) >(S2) ... >(SN) > /dev/null`
  74
  75 The cool thing is that, because the pipe is always read (`tail -f ... > /dev/null`),
  76 the publishers are never blocked, so we get a live stream of events to which we
  77 can attach any number of interested subscribers (` ... tee ... `) and, because
  78 the pipe is named, if a subscriber needs to - it too can publish something to
  79 the pipe without being blocked.
  80
  81 ```
  82 parallel    +----------+  +----------+          +----------+
  83 stateless   | sensor_1 |  | sensor_2 |    ...   | sensor_n |
  84 collectors  +----------+  +----------+          +----------+
  85                  |             |           |         |
  86                data          data        data      data
  87                  |             |           |         |
  88                  V             V           V         V
  89 multiplexing     +-------------+-----------+---------+
  90 to a pipe                      |
  91                                |
  92                                V
  93 copying to       +-------------+-+---------+---------+
  94 subscribers      |               |         |         |
  95                  V               V         V         V
  96               +------------+         ...      +----------------+
  97 any number of | status bar |                  | energy monitor |
  98 parallel      +------------+                  +----------------+
  99 subscribers      |                                    |
 100                  V                                    V
 101               +----------------+              +-------------+
 102               | xsetroot -name |              | notify-send |
 103               +----------------+              +-------------+
 104 ```
 105
 106 ### 1.0
 107
 108 This was an improvement of having everything in one script, but the controller
 109 was still way too complicated for no good reason.
 110
 111 ```
 112 parallel    +----------+  +----------+          +----------+
 113 stateless   | sensor_1 |  | sensor_2 |    ...   | sensor_n |
 114 collectors  +----------+  +----------+          +----------+
 115                  |             |           |         |
 116                data          data        data      data
 117                  |             |           |         |
 118                  V             V           V         V
 119 serial      +----------------------------------------------+
 120 stateful    |                controller                    |
 121 observer    +----------------------------------------------+
 122                                |
 123                        decision messages
 124 decision                       |
 125 messages                       |
 126 copied to                      |
 127 any number                     |
 128 of interested                  |
 129 filter/actuator                |
 130 combinations                   |
 131                                |
 132                                V
 133                  +-------------+-+---------+---------+
 134                  |               |         |         |
 135                  V               V         V         V
 136 parallel    +------------+ +------------+     +------------+
 137 stateless   | filter_1   | | filter_2   | ... | filter_n   |
 138 filters     +------------+ +------------+     +------------+
 139                  |               |         |         |
 140                  V               V         V         V
 141 parallel    +------------+ +------------+     +------------+
 142 stateless   | actuator_1 | | actuator_2 | ... | actuator_n |
 143 executors   +------------+ +------------+     +------------+
 144                  |              |          |         |
 145               commands       commands   commands  commands
 146                  |              |          |         |
 147                  V              V          V         V
 148             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 149             ~~~~~~~~~~~~~ operating system ~~~~~~~~~~~~~~~~~
 150             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 151 ```
 152
 153 ### Actuator
 154 Actuator is anything that takes action upon controller messages. A few generic
 155 ones are included:
 156
 157 - `khatus_actuate_alert_to_notify_send`
 158 - `khatus_actuate_status_bar_to_xsetroot_name`
 159
 160 and, by default, are left disconnected from the data feed, so if desired - need
 161 to be manually attached when starting `khatus`. See usage section.
 162
 163 ### Errors
 164 Any errors encountered by any sensor are propagated as alerts by the
 165 controller, which are in turn actualized as desktop notifications by the
 166 `khatus_actuate_alert_to_notify_send` actuator:
 167
 168 ![screenshot-self-error-propagation](screenshot-self-error-propagation.jpg)
 169
 170 Redesign notes
 171 --------------
 172
 173 - controller should not do formatting
 174 - need in-memory db for diskless feedback/throttling and cache
 175 - decouple sensor execution from sleep, i.e. a sensor is blocked not by sleep
 176   process directly, but by reading of a pipe, to where a sleep process will
 177   write a message announcing interval completion and thus signaling execution.
 178   This will allow us to manually signal a sensor to update (concretely - I just
 179   openned my laptop from sleep and want to force the weather to update
 180   immediately); likewise, the sleep process should be blocked on pipe-read
 181   until sensor execution is complete - this will allow us to reconfigure
 182   intervals at runtime (which seems like a better idea than the above in-memory
 183   DB one).