Skip to content

U0002 ui-blocking-call

Rule: UI code never blocks the UI thread on files, the network, processes or sleeps.

Code U0002 (stable, never reused)
Id ui-blocking-call
Category ui
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small off
small-workspace off
medium off
big off
ai off
embedded off
ui warn a blocking call on the UI thread freezes the window; an estimate, since a function may run on a worker that the lint does not see
egui warn a blocking call in a function that draws or updates the UI freezes the window; an estimate, without types
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
functions list of strings ["std::thread::sleep", "std::fs::read", "std::fs::read_to_string", "std::fs::write", "std::fs::read_dir", "std::fs::copy", "std::fs::rename", "std::fs::remove_file", "std::fs::remove_dir_all", "std::fs::create_dir_all", "std::fs::metadata", "std::fs::File::open", "std::fs::File::create", "std::net::TcpStream::connect", "reqwest::blocking::get", "ureq::get", "ureq::post", "futures::executor::block_on", "pollster::block_on"] functions that block until a file, a peer, a process or a timer is done
methods list of strings ["blocking_read", "blocking_write", "blocking_lock", "blocking_recv", "blocking_send", "block_on"] methods that block
command-paths list of strings ["std::process::Command::new"] constructors of a process command
command-methods list of strings ["output", "status", "wait", "wait_with_output"] methods of a command chain that wait for the process
spawners list of strings ["spawn", "spawn_blocking", "spawn_local", "execute", "scope"] calls whose closures and async blocks run off the UI thread
skip-fns list of strings ["main"] functions that run before the UI does
ui-types list of strings [] parameter types of a function that runs on the UI thread; empty: every function of a UI crate
toolkits list of strings ["egui", "eframe", "iced", "slint", "gtk4", "relm4", "dioxus", "leptos", "yew", "floem", "xilem", "makepad-widgets"] UI toolkits: a crate that depends on one directly is a UI crate, unless the crate map says ui = false

Why

A UI draws a frame, waits for input and draws the next one, all on one thread. A call that waits for a disk, a peer, a process or a timer on that thread freezes the window until it returns: no repaint, no input, and on most desktops a "not responding" dialog. zed lints blocking I/O on its foreground thread for the same reason.

The lint reports, in UI crates:

  • calls of the functions in functions (std::fs::read_to_string, std::thread::sleep, ...), resolved through the file's use items;
  • the methods in methods (blocking_read, block_on, ...);
  • a method of command-methods (output, status) on a chain that starts at a command-paths constructor: Command::new("git").arg("log").output().

Code inside a closure or async block passed to one of spawners runs elsewhere and is skipped, as are the functions in skip-fns (main, before the UI runs). With ui-types set (the egui tier: Ui, Context, Frame), only functions that take a parameter of one of these types count: those draw or update the UI, while the rest of a one-crate app may be a worker. Without types, the lint cannot see that a function is only ever called from a worker: findings are estimates.

How to fix

Run the work in a worker (through the spawn wrapper) and hand the result back through a channel; the UI polls it each frame and the worker asks for a repaint when it is done. A lock shared with workers is read with try_read, never blocking_read. Where a function only ever runs on a worker, waive the finding with that reason.

Configure

[lints.ui-blocking-call]
level = "deny"
functions = ["std::thread::sleep", "std::fs::read", "std::fs::read_to_string", "std::fs::write", "std::fs::read_dir", "std::fs::copy", "std::fs::rename", "std::fs::remove_file", "std::fs::remove_dir_all", "std::fs::create_dir_all", "std::fs::metadata", "std::fs::File::open", "std::fs::File::create", "std::net::TcpStream::connect", "reqwest::blocking::get", "ureq::get", "ureq::post", "futures::executor::block_on", "pollster::block_on"]
methods = ["blocking_read", "blocking_write", "blocking_lock", "blocking_recv", "blocking_send", "block_on"]
command-paths = ["std::process::Command::new"]
command-methods = ["output", "status", "wait", "wait_with_output"]
spawners = ["spawn", "spawn_blocking", "spawn_local", "execute", "scope"]
skip-fns = ["main"]
ui-types = []
toolkits = ["egui", "eframe", "iced", "slint", "gtk4", "relm4", "dioxus", "leptos", "yew", "floem", "xilem", "makepad-widgets"]
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(ui-blocking-call) <reason> (waivers); the code works there too, as in [lints.U0002].