feat(kwin): sleep, wake and lock

While the screen is locked or the machine is asleep, KWin sends its clients no
frame callbacks, so nothing komorebi asked for in that time is done: a window
that something else moved stays where it was moved, and the monitors can come
back in another order or at another size. Nothing told komorebi it had happened,
and it kept the layout it had until the next event.

kwin::power now watches for the two ends of it: logind's PrepareForSleep on the
system bus, which only logind may send, and the lock screen's ActiveChanged on
the session bus. When the machine wakes (2.5 seconds after it, while the outputs
are found one after another) or the screen is unlocked (0.6 seconds after it,
once the lock screen has gone), the monitor reconciliator gets a Wake and calls
wake_up: it reconciles the monitors as for an unplug, reads their sizes, follows
the windows to the monitors they are on and tiles every monitor, unless the
window manager is paused. Going to sleep and locking do nothing, and a machine
with no system bus or a session with no lock screen runs without them. The lock
screen is a window of KWin's that the bridge already does not report as an
application window, so it has no tile.

The bridge also compares KWin's active window with the one it last announced
once a second, because the window that is active again after an unlock is not
always announced. vm-lock-sleep locks and unlocks a real Plasma session and
checks that the windows come back to their tiles; a real suspend cannot be
tested in the QEMU guest, only the signal wiring, which tests/power.rs covers on
private buses.

vm-lock-sleep waits for the panel's room before it opens the windows, so that
they are tiled once, and compares the window that was moved with the tile the
daemon has for it when it looks, give or take a cell of the terminal's font, and
not with the frames read earlier: the room can come while the screen is locked,
and the tiles read before are then not the ones. The wait is not a check,
because a session on a machine as slow as TCG may never take the room.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:57 -07:00
1 parent 40eec2f6be
commit 0210ec285a
17 files changed
+913 -26

No files matched your search

+58 -7
View File
@@ -8,11 +8,12 @@ tested, without one.
This page describes that trait, who implements and calls it, where each of its rules is
enforced, the model of the desktop the window manager tiles, the backend that reaches KWin,
how an event about a window becomes a tile, how workspaces are the compositor's desktops, how
a stack hides its windows, how the window manager follows a monitor that changes, how a message
on the daemon's socket is answered, how subscribers are notified of all three, what the orders a
message gives do, what a drag with the pointer does, how the compositor is asked to draw the
borders, how `komorebi.json` configures the daemon, and how the NixOS module runs the daemon. It
grows with the code: each part of the daemon that is added has its place here.
a stack hides its windows, how the window manager follows a monitor that changes and sets the
desktop in order after a sleep or a lock, how a message on the daemon's socket is answered, how
subscribers are notified of all three, what the orders a message gives do, what a drag with the
pointer does, how the compositor is asked to draw the borders, how `komorebi.json` configures the
daemon, and how the NixOS module runs the daemon. It grows with the code: each part of the daemon
that is added has its place here.
## Vocabulary
@@ -70,7 +71,8 @@ grows with the code: each part of the daemon that is added has its place here.
- **Subscriber**: a program that listens on a socket of its own in [`DATA_DIR`] and has
asked the daemon, by the name of that socket, to send it notifications.
- **Monitor notification**: what the KWin backend sends the monitor reconciliator when the
outputs change ([`MonitorNotification`]).
outputs change, and what [`kwin::power`] sends it when the machine wakes or the screen is
unlocked ([`MonitorNotification`]).
- **Notification**: what a subscriber is sent after each event, each message and each change
of the monitors the window manager handles: the event, the message or the change, and the
state after it ([`Notification`]).
@@ -379,6 +381,36 @@ and finds nothing. While the user drags a window nothing moves, since the end of
where that window goes: the method returns at once while [`WindowManager::pending_move_op`] or
[`WindowManager::pending_resize_op`] holds a drag.
## Sleep, wake and lock
While the screen is locked or the machine is asleep, KWin sends its clients no frame callbacks,
so nothing komorebi asked for in that time is done, and the monitors can come back in another
order or size. None of it changes komorebi's state, but each can leave the desktop other than
komorebi left it. [`kwin::power`] watches for the two ends of it and sends a
[`MonitorNotification::Wake`] to the monitor reconciliator:
- `PrepareForSleep` of `org.freedesktop.login1.Manager` on the system bus, with `false`, 2.5
seconds after it. The match rule names `org.freedesktop.login1` as the sender, so that only
logind is believed.
- `ActiveChanged` of `org.freedesktop.ScreenSaver` on the session bus, with `false`, which KDE's
lock screen sends when it goes, 0.6 seconds after it, from any sender.
Going to sleep and locking the screen only log. A session with no lock screen or a machine with
no system bus has nothing to watch, and the daemon logs that and runs. The watchers are tasks of
the runtime of the KWin backend, which [`kwin::connect`] starts with the connection.
[`wake_up`] is what the reconciliator does for a `Wake`: it does what it does for a change of the
set of monitors ([`reconcile_display_change`]), reads the size and work area of every monitor
([`update_monitor_work_areas`]), follows the windows to the monitors they are on
([`WindowManager::follow_windows_to_their_monitors`]), and tiles every monitor
([`WindowManager::retile_all`]). A paused window manager is left alone.
The lock screen is a window of KWin's, with the class `kwin_wayland`, on every desktop and in no
task list, pager or switcher, and the bridge does not report it as an application window, so the
table never has a tile for it. The bridge also compares KWin's active window with the one it
last announced once a second, and announces the active one when they differ, since the window
that is active again after the screen is unlocked is not always announced.
## The command socket
The daemon takes messages on a Unix socket, `komorebi.sock` in [`DATA_DIR`]
@@ -1125,12 +1157,14 @@ module's unit.
- [`monitor_reconciliator`](../../komorebi/src/monitor_reconciliator.rs): the channel the KWin
backend sends [`MonitorNotification`]s on, [`listen_for_notifications`], the thread that
takes them, and [`reconcile_display_change`], which brings the window manager's monitors in
line with the outputs;
line with the outputs, and [`wake_up`], which puts the desktop in order after a wake;
[`reconcile`](../../komorebi/src/reconcile.rs): moves what was on a monitor that went to the
monitors that are left, and every container whose window is on another monitor to that
monitor.
- [`kwin`](../../komorebi/src/kwin/mod.rs): the KWin backend, its D-Bus service and the held
call; [`kwin::state`](../../komorebi/src/kwin/state.rs), the table;
[`kwin::power`](../../komorebi/src/kwin/power.rs), the watchers of logind's sleep signal and the
lock screen's;
[`kwin::kwinrc`](../../komorebi/src/kwin/kwinrc.rs), the editor of the user's `kwinrc`, which
keeps the values it changes and puts them back; the parking desktop is made, swept and removed
in `kwin` and tracked in `kwin::state`; and
@@ -1305,6 +1339,13 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
| A monitor komorebi has not seen gets workspaces of its own | framework path: [`load_monitor_information`] adds the monitors the window manager does not have | `a_monitor_that_was_never_there_gets_windows_of_its_own` | none |
| When KWin reports no output, the window manager keeps the monitors it has | framework path: [`reconcile_display_change`] returns before it removes any | `a_desktop_that_reports_no_monitor_is_left_as_it_was` | none |
| A monitor is only removed once its windows are on the monitors that are left | framework path: [`reconcile_display_change`] evacuates every monitor that went before it removes any | `the_windows_of_a_monitor_that_goes_are_tiled_on_the_one_that_is_left` | none |
| Waking up and unlocking each make the window manager look at the desktop again, once, after a delay, and going to sleep and locking do not | framework path: [`kwin::power`] sends a `Wake` after each of the two signals' `false`, and nothing for `true` | `waking_and_unlocking_make_the_window_manager_look_again_and_going_to_sleep_and_locking_do_not` (private buses) | none |
| Only logind is believed about the machine going to sleep | framework path: the match rule of the system bus names `org.freedesktop.login1` as the sender | the same test sends as another connection too | none |
| komorebi runs without a system bus or a lock screen | framework path: [`kwin::power`] logs that it is not watching, and a session with no lock screen sends no signal | none | none |
| On waking, the windows are where their tiles are, and a monitor that went while asleep is dealt with | framework path: [`wake_up`] reconciles the monitors, follows the windows and tiles every monitor | `windows_that_did_not_get_where_they_were_sent_while_the_screen_was_off_are_put_there_on_waking`, `a_monitor_unplugged_while_the_machine_slept_is_dealt_with_on_waking` | none |
| A paused window manager moves no window on waking | framework path: [`wake_up`] returns first when the window manager is paused | `a_paused_window_manager_is_left_alone_on_waking` | none |
| The lock screen has no tile | convention in the bridge: a window of the class `kwin_wayland` is not an application window | `dialogs, the lock screen and windows nobody can switch to are not application windows`, `vm-lock-sleep` ("the lock screen is not one") | none |
| komorebi's idea of the focus follows KWin's after the screen is unlocked | convention in the bridge: it announces KWin's active window when it is not the one it last announced, once a second | `the active window is announced when KWin has another than the one last announced, once`, `vm-lock-sleep` ("its idea of the focus is KWin's") | none |
| A subscriber that wants only changes of the state is sent every change of the monitors | framework path: [`notify_subscribers`] treats a monitor notification as an override of the filter | `a_change_of_the_monitors_is_sent_to_a_subscriber_that_filters_state_changes_too` | none |
| Moving the focus moves no window | test | `focus_gives_the_focus_to_the_window_on_that_side_and_moves_nothing`, `vm-core-e2e` ("moving the focus moved no window") | none |
| A subscriber that is gone is dropped, not retried | test | `a_subscriber_that_is_gone_is_dropped_and_not_tried_again` | none |
@@ -1537,6 +1578,11 @@ A window is shown, and ends up on a tile:
output, against the fake;
[`nix/tests/vm/suites/hotplug`](../../nix/tests/vm/suites/hotplug/test.py), both against a real
KWin with two outputs.
- [`komorebi/tests/wake.rs`](../../komorebi/tests/wake.rs): the desktop after a wake, against the
fake; [`komorebi/tests/power.rs`](../../komorebi/tests/power.rs), the signals of logind and
of the lock screen, on private buses;
[`nix/tests/vm/suites/lock-sleep`](../../nix/tests/vm/suites/lock-sleep/test.py), the lock
screen of a real Plasma session.
- [`komorebi/tests/workspaces.rs`](../../komorebi/tests/workspaces.rs): workspaces as the
fake's desktops;
[`komorebi/tests/workspace_commands.rs`](../../komorebi/tests/workspace_commands.rs), naming,
@@ -1775,6 +1821,11 @@ A window is shown, and ends up on a tile:
[`MonitorNotification::DisplayConnectionChange`]: ../../komorebi/src/monitor_reconciliator.rs
[`reconcile_display_change`]: ../../komorebi/src/monitor_reconciliator.rs
[`insert_in_monitor_cache`]: ../../komorebi/src/monitor_reconciliator.rs
[`kwin::power`]: ../../komorebi/src/kwin/power.rs
[`MonitorNotification::Wake`]: ../../komorebi/src/monitor_reconciliator.rs
[`wake_up`]: ../../komorebi/src/monitor_reconciliator.rs
[`WindowManager::retile_all`]: ../../komorebi/src/window_manager.rs
[`kwin::connect`]: ../../komorebi/src/kwin/mod.rs
[`WindowManager::evacuate_monitor`]: ../../komorebi/src/reconcile.rs
[`WindowManager::follow_windows_to_their_monitors`]: ../../komorebi/src/reconcile.rs
[`settle_later`]: ../../komorebi/src/monitor_reconciliator.rs
+20
View File
@@ -624,3 +624,23 @@ reports on another output is handled the same way, looking at every window and n
one, since when one has moved others may have too. komorebi tiles at once the windows it knows
about when the monitors change, such as those of an output that went; the ones KWin moves
afterwards are tiled up to 1.5 seconds later.
## Why does komorebi look at the desktop again when the machine wakes and the screen is unlocked?
Because nothing komorebi asked for while the screen was locked or the machine asleep was done.
In that time KWin sends its clients no frame callbacks, so a window that was asked to move did
not, a window that something else moved stayed where it was moved, and the monitors can come
back in another order or at another size. Neither an unlock nor a wake is an event about a
window, so komorebi listens for the two signals that say it happened, logind's `PrepareForSleep`
and the lock screen's `ActiveChanged`, and then reads the monitors, finds where every window is,
and puts each in its tile. It waits first: 0.6 seconds after an unlock, because the lock screen
goes before the windows can be seen, and 2.5 seconds after a wake, because the outputs are found
again one after another and the compositor moves windows about as they are. Going to sleep and
locking the screen change nothing, so komorebi does nothing for them.
## Why does the bridge compare the active window with the last one it announced?
Because after the screen is unlocked the window that is active again is not always announced,
and komorebi's idea of the focus would stay the one it had. Once a second the bridge compares the
window KWin has active with the one it last announced, and announces the active one when they
differ. It costs a comparison of two ids a second.
+30 -4
View File
@@ -126,8 +126,16 @@ the windows and outputs it finds, and from then on every window that opens, clos
focus, is minimized or brought back, moves or changes size, the start and the end of every drag
of a window by the user, and every change of the outputs (one that changes resolution or scale,
and the room a panel leaves). KWin has no signal for that room, so the script looks at the
outputs again when a dock window opens, closes or moves, and once a second. The daemon waits up
to 10 seconds for the first report and does not start without it.
outputs again when a dock window opens, closes or moves, and once a second; it also compares
KWin's active window with the one it last reported once a second. The daemon waits up to 10
seconds for the first report and does not start without it.
It also watches for the machine waking up and the screen being unlocked, with two signals that
are not KWin's ([D-Bus](#d-bus)): logind's `PrepareForSleep` on the system bus, and the lock
screen's `ActiveChanged` on the session bus. Either one makes it look at the monitors and at
where every window is again, after a delay (2.5 seconds after a wake, 0.6 after an unlock). Where
there is no system bus, as in a container, it logs that it is not watching for sleep, and
carries on.
Before it loads the script, it turns on KWin's per-output virtual desktops in the user's
`kwinrc` (`[Windows] PerOutputVirtualDesktops=true`), unless they are on, and asks KWin to
@@ -191,8 +199,9 @@ directory keeps the user's value), or the session ends.
### A headless KWin
`kwin_wayland --virtual` behaves like the KWin of a session for everything komorebi does:
the VM tests run the daemon against one, on a private session bus of its own. It cannot draw
`kwin_wayland --virtual` behaves like the KWin of a session for everything komorebi does but
the lock screen, which it has none of (`vm-lock-sleep` runs in a Plasma session): the VM tests
run the daemon against one, on a private session bus of its own. It cannot draw
(see [Rendering](#rendering-in-virtual-machines-and-over-rdp)), so nothing that depends on
pixels can be tested against it. Started with `--no-global-shortcuts`, as the VM tests start
it, KWin does not own `org.kde.kglobalaccel`, and the pointer does not follow the focus; the
@@ -238,6 +247,16 @@ What komorebi calls:
| `org.kde.KWin` | `/VirtualDesktopManager` | `org.kde.KWin.VirtualDesktopManager` | the properties `desktops` and `count`, `createDesktop(us)`, `setDesktopName(ss)`, `removeDesktop(s)` | when a workspace has no desktop, and at start; `createDesktop` also for the parking desktop, the first time a window is hidden, and `removeDesktop` for it when komorebi stops and for one a killed run left |
| `org.kde.plasmashell` | `/PlasmaShell` | `org.kde.PlasmaShell` | `evaluateScript(s) -> s`, `wallpaper(u) -> a{sv}`, `setWallpaper(sa{sv}u)` | when a workspace with a wallpaper comes into view ([The Plasma shell](#the-plasma-shell)) |
What komorebi listens to, for the machine sleeping and the screen being locked:
| Bus | Sender | Interface | Signal | Meaning |
|---|---|---|---|---|
| system | `org.freedesktop.login1` | `org.freedesktop.login1.Manager` | `PrepareForSleep(b)` | the machine is going to sleep (true) or has woken up (false) |
| session | any | `org.freedesktop.ScreenSaver` | `ActiveChanged(b)` | the lock screen came up (true) or went away (false) |
Only logind is believed about sleep. The lock screen's signal is taken from any sender on the
session bus.
The property `desktops` is introspected as `a(iss)`, a position, an id and a name for each
desktop, and the value on the wire is `a(uss)`: komorebi reads it as that. It is read uncached,
since a read right after `createDesktop` has to see the new desktop.
@@ -448,6 +467,13 @@ with two outputs of 1920x1080:
it was on. KWin raises `outputChanged` for it, which `vm-hotplug` shows by moving windows with
`kdotool windowmove`, as a shortcut or the window menu would.
## Sleep and lock
At time of writing (2026-10-27), a real suspend and resume is not tested: the QEMU guests the VM
tests run in have no way to wake from one. The signals are tested on private buses
(`komorebi/tests/power.rs`), and the lock screen against a real KWin in a Plasma session
(`vm-lock-sleep`, which locks and unlocks with `loginctl lock-session` and `unlock-session`).
## How long a retile takes
Measured by the VM test `vm-latency` at time of writing (2026-10-27), in a headless KWin 6.8.1