Use braces in elses which follow multi-statement ifs
[khatus.git] / 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).
This page took 0.077291 seconds and 4 git commands to generate.