From 3466fc0a66a43bf2f959673ff303e9037488a173 Mon Sep 17 00:00:00 2001 From: Jon Heinritz Date: Sun, 2 Mar 2025 20:33:40 +0100 Subject: ipc: document the new socket behavior --- niri-ipc/src/lib.rs | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/niri-ipc/src/lib.rs b/niri-ipc/src/lib.rs index 6d7ea92d..708cea5e 100644 --- a/niri-ipc/src/lib.rs +++ b/niri-ipc/src/lib.rs @@ -1,8 +1,23 @@ //! Types for communicating with niri via IPC. //! -//! After connecting to the niri socket, you can send a single [`Request`] and receive a single -//! [`Reply`], which is a `Result` wrapping a [`Response`]. If you requested an event stream, you -//! can keep reading [`Event`]s from the socket after the response. +//! After connecting to the niri socket, you can send [`Request`]s. Niri will process them one by +//! one, in order, and to each request it will respond with a single [`Reply`], which is a `Result` +//! wrapping a [`Response`]. +//! +//! If you send a [`Request::EventStream`], niri will *stop* reading subsequent [`Request`]s, and +//! will start continuously writing compositor [`Event`]s to the socket. If you'd like to read an +//! event stream and write more requests at the same time, you need to use two IPC sockets. +//! +//!
+//! +//! Requests are *always* processed separately. Time passes between requests, even when sending +//! multiple requests to the socket at once. For example, sending [`Request::Workspaces`] and +//! [`Request::Windows`] together may not return consistent results (e.g. a window may open on a +//! new workspace in-between the two responses). This goes for actions too: sending +//! [`Action::FocusWindow`] and [Action::CloseWindow] { id: None } together may close +//! the wrong window because a different window got focused in-between these requests. +//! +//!
//! //! You can use the [`socket::Socket`] helper if you're fine with blocking communication. However, //! it is a fairly simple helper, so if you need async, or if you're using a different language, @@ -12,7 +27,9 @@ //! 2. Connect to the socket and write a JSON-formatted [`Request`] on a single line. You can follow //! up with a line break and a flush, or just flush and shutdown the write end of the socket. //! 3. Niri will respond with a single line JSON-formatted [`Reply`]. -//! 4. If you requested an event stream, niri will keep responding with JSON-formatted [`Event`]s, +//! 4. You can keep writing [`Request`]s, each on a single line, and read [`Reply`]s, also each on a +//! separate line. +//! 5. After you request an event stream, niri will keep responding with JSON-formatted [`Event`]s, //! on a single line each. //! //! ## Backwards compatibility -- cgit