mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-18 22:58:34 +01:00
feat(wm): subscribe to notifications
A program such as a status bar has to follow the window manager, and so far it could only ask: komorebi on Windows and on macOS sends notifications for that. The daemon now keeps subscribers, each a Unix socket in its data directory that a program listens on, and after each event and each message it handles, it connects to every subscriber and writes the event or the message with the state after it. A subscriber can ask to be sent only what changed the state; a window that is shown and a new subscription are always sent, so a subscriber has the state as soon as it subscribes. A subscriber that cannot be connected to is dropped with its socket file and not tried again, and a stopping daemon closes an empty connection to each one. komorebic gains subscribe-socket and unsubscribe-socket, and komorebi-client subscribe and subscribe_with_options, which bind the socket and subscribe. The tests subscribe through real sockets against the fake desktop: a shown window is sent with the state that has it, a subscriber that filters is not sent a question that changed nothing, and one that is gone is dropped.
This commit is contained in:
1 parent
6f657e53e3
commit
e2d757bbb0
20 files changed
+1078
-25
No files matched your search
@@ -66,6 +66,9 @@ a window that was moved by hand back on its tile.
|
||||
|
||||
When the daemon is not running, these commands fail: there is no socket to write to.
|
||||
|
||||
A program that wants to know what komorebi does without asking can subscribe to its
|
||||
notifications instead ([Subscribing to notifications](subscribing-to-notifications.md)).
|
||||
|
||||
## The socket and the data directory
|
||||
|
||||
The daemon listens on `komorebi.sock` in its data directory, `$XDG_RUNTIME_DIR/komorebi`
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
# Subscribing to notifications
|
||||
|
||||
A program such as a status bar, a widget or a script can follow what komorebi does by
|
||||
subscribing to its notifications. After each event the window manager handles (a window
|
||||
was shown, closed, focused, minimized or restored) and each message it takes on its socket,
|
||||
the daemon sends every subscriber a notification: the event or the message, and the state
|
||||
of the window manager after it.
|
||||
|
||||
## Subscribing
|
||||
|
||||
A subscriber listens on a Unix socket of its own in the daemon's data directory,
|
||||
`$XDG_RUNTIME_DIR/komorebi` (on NixOS and most systemd distributions,
|
||||
`/run/user/<uid>/komorebi`), and tells the daemon the name of the socket with
|
||||
[`komorebic subscribe-socket`](../cli/subscribe-socket.md). The socket has to exist before
|
||||
it subscribes: the daemon sends the notification of the subscription at once, and removes a
|
||||
subscriber it cannot connect to.
|
||||
|
||||
With [socat](http://www.dest-unreach.org/socat/), a shell can subscribe and print every
|
||||
notification:
|
||||
|
||||
```sh
|
||||
socat -u UNIX-LISTEN:"$XDG_RUNTIME_DIR/komorebi/bar.sock",fork STDOUT &
|
||||
komorebic subscribe-socket bar.sock
|
||||
```
|
||||
|
||||
[`komorebic unsubscribe-socket bar.sock`](../cli/unsubscribe-socket.md) stops the
|
||||
notifications.
|
||||
|
||||
## Notifications
|
||||
|
||||
The daemon sends each notification on a new connection to the subscriber's socket: it
|
||||
connects, writes one JSON object, and closes the connection. There is no newline after the
|
||||
object. The first notification a subscriber receives is the one of its subscription.
|
||||
|
||||
A notification has two fields:
|
||||
|
||||
- `event`: the event or the message. An event is a window event, with the signal it came
|
||||
from and the window, such as
|
||||
`{"type":"Show","content":[{"type":"KWin","content":"WindowAdded"},{"id":...}]}`. A
|
||||
message is written the way a client writes it on the daemon's socket, such as
|
||||
`{"type":"Retile"}`.
|
||||
- `state`: the state of the window manager after it, with the same fields as what
|
||||
[`komorebic state`](../cli/state.md) prints, on one line.
|
||||
|
||||
An event about a window that komorebi does not manage, and a message that fails, are not
|
||||
sent.
|
||||
|
||||
## Only when something changed
|
||||
|
||||
A subscriber can ask to be sent a notification only when the event or the message changed
|
||||
the state, with the `filter_state_changes` option. It is still sent the notification of a
|
||||
window that is shown and of every new subscription, so it receives the state as soon as it
|
||||
subscribes. `komorebic subscribe-socket` has no option for it; a program writes the message
|
||||
on the daemon's socket itself:
|
||||
|
||||
```sh
|
||||
printf '%s' '{"type":"AddSubscriberSocketWithOptions","content":["bar.sock",{"filter_state_changes":true}]}' |
|
||||
socat - UNIX-CONNECT:"$XDG_RUNTIME_DIR/komorebi/komorebi.sock"
|
||||
```
|
||||
|
||||
## When a subscriber goes away
|
||||
|
||||
A subscriber that the daemon cannot connect to, because its program has exited or its
|
||||
socket was removed, is removed at the next notification, and its socket file with it. The
|
||||
daemon does not try it again: a program that wants notifications again subscribes again.
|
||||
The daemon keeps its subscribers only while it runs, so after a restart every program has
|
||||
to subscribe again.
|
||||
|
||||
When the daemon stops, it connects to each subscriber and closes the connection without
|
||||
writing anything.
|
||||
|
||||
A subscriber should accept and read every connection as it comes. The daemon writes each
|
||||
notification while the window manager is locked, and waits when the socket's buffer is
|
||||
full, so a subscriber that stops reading can hold up the window manager. While it is held
|
||||
up, the window events KWin reports wait for it, and once 20 are waiting the daemon drops
|
||||
the ones that come after them.
|
||||
|
||||
## In Rust
|
||||
|
||||
The `komorebi-client` crate has `subscribe` and `subscribe_with_options`, which listen on
|
||||
the socket, subscribe, and return the listener: each connection on it is one
|
||||
`Notification`. `cargo doc --package komorebi-client --open` shows their documentation,
|
||||
with an example.
|
||||
Reference in new issue
Block a user