Skip to main content

codewhale_runtime/
sleep_guard.rs

1//! Keep the host from idling into sleep while a turn is in flight.
2//!
3//! A suspended host cannot run the engine, so nothing here survives a real
4//! suspend. A provider request interrupted by sleep retains an unknown outcome
5//! and is not automatically replayed. This module prevents an unattended
6//! machine from idling into sleep in
7//! the middle of a turn, which is how a long turn gets lost with no error at
8//! all.
9//!
10//! Scope, stated so nobody expects more than it does:
11//!
12//! - It holds the platform's *idle-sleep* assertion only. An explicit `sleep`/
13//!   `pmset sleepnow`, a closed lid, or a low battery still wins — refusing
14//!   those is the machine owner's call, not a running task's.
15//! - It is held for the duration of a turn and released on drop, so the host's
16//!   power behaviour outside a turn is untouched.
17//! - It follows the same gate as the rest of the host-facing chrome
18//!   (`EngineConfig::terminal_chrome_enabled`): an interactive TUI turn holds
19//!   it, while headless hosts — `exec`, app-server, CI — never do. A dedicated
20//!   `[tui]` opt-out key is not implemented yet; the headless gate is the
21//!   escape hatch today.
22//! - Windows is not implemented. `SetThreadExecutionState` is thread-affine —
23//!   the release has to happen on the thread that set it, which a guard that
24//!   travels with a turn cannot promise. Rather than ship an untested holder
25//!   that might silently never release, this is a no-op there for now.
26//!
27//! Release is `Drop` and never cached: a leaked inhibitor would keep a laptop
28//! awake forever, which is worse than the problem this solves.
29//!
30//! The inhibitor is a `tokio::process` child, because the guard lives inside
31//! `Engine::run_turn` on the runtime: the spawn registers with the runtime,
32//! `kill_on_drop` sends the release signal, and the runtime reaps the child —
33//! no `wait` runs inline on a worker (#6149). `hold` therefore has to be
34//! called from within a Tokio runtime context.
35//!
36//! `Drop` never runs when the process is killed, crashes or calls
37//! `process::exit`, so each inhibitor is also tied to this process's lifetime
38//! independently of the guard: on macOS `caffeinate -w <pid>` exits with the
39//! process it watches, and on Linux the pipe below closes with it.
40//!
41//! On Linux the lock is held by `systemd-inhibit` around a child of its own,
42//! and a kill is never forwarded to that grandchild. The command is therefore
43//! `cat` reading a pipe this guard holds: dropping the guard closes the pipe,
44//! `cat` exits on EOF, and `systemd-inhibit` follows — nothing is left behind.
45
46#[cfg(unix)]
47use tokio::process::Child;
48// Only the macOS and Linux inhibitors spawn anything; every other Unix
49// (Android, the BSDs, illumos) is a no-op and would see these as dead.
50#[cfg(any(target_os = "macos", target_os = "linux"))]
51use std::process::Stdio;
52#[cfg(any(target_os = "macos", target_os = "linux"))]
53use tokio::process::Command;
54
55/// An idle-sleep assertion held for as long as this value lives.
56pub struct SleepGuard {
57    /// The platform inhibitor process, when one was started. `None` means the
58    /// platform has no implementation, or the process could not be started —
59    /// keeping the host awake is best-effort and must never fail a turn.
60    /// Dropping it is the release: the child is spawned with `kill_on_drop`.
61    #[cfg(unix)]
62    child: Option<Child>,
63}
64
65impl SleepGuard {
66    /// Hold the host awake until the returned guard drops. Call it from the
67    /// Tokio runtime: the inhibitor is a `tokio::process` child.
68    #[must_use]
69    pub fn hold() -> Self {
70        #[cfg(unix)]
71        {
72            Self {
73                child: start_inhibitor(),
74            }
75        }
76        #[cfg(not(unix))]
77        {
78            Self {}
79        }
80    }
81
82    /// The inhibitor's process id, for diagnostics and tests. Absent when the
83    /// platform is a no-op or the process did not start.
84    #[cfg(all(test, unix))]
85    pub(crate) fn inhibitor_pid(&self) -> Option<u32> {
86        self.child.as_ref().and_then(Child::id)
87    }
88}
89
90#[cfg(unix)]
91impl Drop for SleepGuard {
92    fn drop(&mut self) {
93        // Releasing is dropping the child: `kill_on_drop` sends the signal
94        // here, synchronously, and the runtime reaps the process afterwards.
95        // Explicit so the field's purpose is code rather than a lint waiver.
96        drop(self.child.take());
97    }
98}
99
100/// `-i` prevents idle sleep. `Drop` kills caffeinate, and macOS releases the
101/// assertion with the process. `-w` watches this process too: a crash, kill
102/// or `process::exit` skips `Drop`, and the reparented caffeinate would
103/// otherwise keep the host awake indefinitely.
104#[cfg(target_os = "macos")]
105fn start_inhibitor() -> Option<Child> {
106    let pid = std::process::id().to_string();
107    spawn("caffeinate", &caffeinate_args(&pid))
108}
109
110#[cfg(target_os = "macos")]
111fn caffeinate_args(watched_pid: &str) -> [&str; 3] {
112    ["-i", "-w", watched_pid]
113}
114
115/// `--what=idle` only: an explicit suspend or a closed lid is still honoured.
116/// `cat` on the guard's pipe is the command whose lifetime holds the block
117/// open: it exits on EOF when the guard drops, which no signal sent to
118/// `systemd-inhibit` could make a `sleep infinity` grandchild do.
119#[cfg(target_os = "linux")]
120fn start_inhibitor() -> Option<Child> {
121    spawn(
122        "systemd-inhibit",
123        &[
124            "--what=idle",
125            "--why=Codewhale turn in flight",
126            "--mode=block",
127            "cat",
128        ],
129    )
130}
131
132/// Everything else Unix (BSD, illumos, …) has no inhibitor this module knows.
133#[cfg(all(unix, not(any(target_os = "macos", target_os = "linux"))))]
134fn start_inhibitor() -> Option<Child> {
135    None
136}
137
138#[cfg(any(target_os = "macos", target_os = "linux"))]
139fn spawn(program: &str, args: &[&str]) -> Option<Child> {
140    Command::new(program)
141        .args(args)
142        // The pipe is never written to: closing it when the guard drops is
143        // what ends an inhibitor's own child (see the Linux inhibitor).
144        .stdin(Stdio::piped())
145        .stdout(Stdio::null())
146        .stderr(Stdio::null())
147        // Killing the inhibitor is what releases the assertion; the runtime
148        // reaps the child afterwards, so nothing here waits inline.
149        .kill_on_drop(true)
150        .spawn()
151        .ok()
152}
153
154#[cfg(all(test, unix))]
155mod tests {
156    use super::*;
157
158    /// Whether the process is still there. `kill(pid, 0)` asks the kernel
159    /// without touching the process, so this cannot perturb the guard.
160    fn alive(pid: u32) -> bool {
161        // SAFETY: signal 0 performs the permission/existence check only.
162        unsafe { libc::kill(pid as libc::pid_t, 0) == 0 }
163    }
164
165    /// The kill is sent on drop and the runtime reaps the child on the next
166    /// `SIGCHLD`, so "gone" is a short poll rather than an instant fact. If
167    /// the pid were reused by a new process in that window the test would be
168    /// racing itself, which is why callers assert on the guard's own child.
169    async fn released(pid: u32) -> bool {
170        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(5);
171        while alive(pid) {
172            if tokio::time::Instant::now() >= deadline {
173                return false;
174            }
175            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
176        }
177        true
178    }
179
180    #[tokio::test]
181    #[cfg(any(target_os = "macos", target_os = "linux"))]
182    async fn the_inhibitor_lives_exactly_as_long_as_the_guard() {
183        let guard = SleepGuard::hold();
184        let pid = guard
185            .inhibitor_pid()
186            .expect("this platform starts an inhibitor");
187        assert!(alive(pid), "the inhibitor must be running while held");
188
189        drop(guard);
190
191        assert!(
192            released(pid).await,
193            "a released guard must not leave an inhibitor keeping the host awake"
194        );
195    }
196
197    /// Linux: `systemd-inhibit` holds the lock around a child of its own and a
198    /// kill never reaches that grandchild — the guard's pipe is what ends it.
199    /// Without logind the inhibitor exits at once and the list is empty, so
200    /// this proves something only where an inhibitor really runs.
201    #[tokio::test]
202    #[cfg(target_os = "linux")]
203    async fn a_released_guard_leaves_no_grandchild_behind() {
204        let guard = SleepGuard::hold();
205        let pid = guard
206            .inhibitor_pid()
207            .expect("this platform starts an inhibitor");
208        // Give the inhibitor a moment to fork its command.
209        tokio::time::sleep(std::time::Duration::from_millis(200)).await;
210        let grandchildren: Vec<u32> =
211            tokio::fs::read_to_string(format!("/proc/{pid}/task/{pid}/children"))
212                .await
213                .unwrap_or_default()
214                .split_whitespace()
215                .filter_map(|child| child.parse().ok())
216                .collect();
217
218        drop(guard);
219
220        assert!(released(pid).await, "the inhibitor itself must be gone");
221        for grandchild in grandchildren {
222            assert!(
223                released(grandchild).await,
224                "process {grandchild} outlived the guard: the inhibitor's command must end with the guard's pipe"
225            );
226        }
227    }
228
229    /// macOS: when the owning process dies without running `Drop`, the
230    /// inhibitor must exit on its own. A stand-in owner is killed here, since
231    /// the test cannot kill its own process.
232    #[tokio::test]
233    #[cfg(target_os = "macos")]
234    async fn the_inhibitor_exits_when_its_owner_dies_without_dropping_the_guard() {
235        let mut owner = Command::new("sleep")
236            .arg("60")
237            .kill_on_drop(true)
238            .spawn()
239            .expect("start a stand-in owner process");
240        let owner_pid = owner.id().expect("owner pid").to_string();
241        let mut inhibitor = spawn("caffeinate", &caffeinate_args(&owner_pid))
242            .expect("start caffeinate watching the stand-in owner");
243        let pid = inhibitor.id().expect("inhibitor pid");
244        assert!(
245            alive(pid),
246            "the inhibitor must be running while its owner lives"
247        );
248
249        // The owner dies without anything killing the inhibitor, as when the
250        // process is SIGKILLed and the guard's `Drop` never runs.
251        owner.kill().await.expect("kill the stand-in owner");
252
253        // Waiting (rather than probing the pid) also reaps the child; if it
254        // never exits, dropping it at the end of the test kills it.
255        let exited =
256            tokio::time::timeout(std::time::Duration::from_secs(5), inhibitor.wait()).await;
257        assert!(
258            exited.is_ok(),
259            "an inhibitor whose owner died must not keep the host awake"
260        );
261    }
262
263    /// macOS: the guard a turn really takes must watch this process. The
264    /// test above proves `-w` ends caffeinate with a stand-in owner; this one
265    /// proves `hold` passes it, and passes our own pid.
266    #[tokio::test]
267    #[cfg(target_os = "macos")]
268    async fn a_held_guard_watches_the_process_that_holds_it() {
269        let guard = SleepGuard::hold();
270        let pid = guard
271            .inhibitor_pid()
272            .expect("this platform starts an inhibitor");
273        let ps = std::process::Command::new("ps")
274            .args(["-o", "args=", "-p", &pid.to_string()])
275            .output()
276            .expect("run ps");
277        let args = String::from_utf8_lossy(&ps.stdout);
278        assert_eq!(
279            args.trim(),
280            format!("caffeinate -i -w {}", std::process::id()),
281            "the inhibitor must end with the process whose turn it holds"
282        );
283    }
284
285    #[tokio::test]
286    #[cfg(any(target_os = "macos", target_os = "linux"))]
287    async fn holding_twice_holds_two_independent_inhibitors() {
288        // Turns are serialized, but nothing here should assume it: two guards
289        // must not share one process, or the first drop would release both.
290        let first = SleepGuard::hold();
291        let second = SleepGuard::hold();
292        let (a, b) = (
293            first.inhibitor_pid().expect("first inhibitor"),
294            second.inhibitor_pid().expect("second inhibitor"),
295        );
296        assert_ne!(a, b, "each guard owns its own inhibitor process");
297        drop(first);
298        assert!(released(a).await, "the first guard released only its own");
299        assert!(alive(b), "the second guard still holds the host awake");
300    }
301}