Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Rust Tokio: Blocking the Runtime and spawn_blocking Fixes

A synchronous call inside an async fn stops the worker that drives every other task on it, timers included. Detection, spawn_blocking, and the guard-across-await trap.

~5 min readRust
#Rust#Tokio#Async#Performance
3D illustration of a runtime ring of worker threads with one gear jammed by a solid amber block, a side channel to a separate thread pool

Introduction & Quick Summary

Symptom. A Tokio service handles 200 requests per second in benchmarks and 4 per second in production, and the slowdown comes with silence: no errors, no panics, timers firing late or never, requests that were accepted that never complete. tokio::time::sleep(Duration::from_millis(10)) sometimes takes two seconds. The tokio-console task list shows a handful of tasks busy for hundreds of milliseconds each.

Cause. Every Tokio worker thread runs a loop that drives all futures assigned to it. If any future blocks its thread — std::thread::sleep, a synchronous file read, a heavy CPU loop, a std::sync::Mutex held across an .await, a synchronous database driver — that worker stops driving every other task on it, including the timer wheel. With the default worker_threads equal to the CPU count, a few blocking tasks stop the whole runtime. It compiles because nothing about async fn prevents blocking; the failure is at runtime and looks like slowness rather than a bug.

Fix. Use tokio::time::sleep instead of std::thread::sleep, tokio::fs/tokio::net instead of std::fs/std::net, tokio::sync::Mutex when a guard must live across an .await, and move genuinely blocking or CPU-heavy work to spawn_blocking or a dedicated thread. Then measure: worker busy time and task poll duration are the numbers that show whether it is fixed.

Core Mechanics, Signatures & Reproducible Setup

The runtime is a fixed set of threads with a work-stealing queue. Blocking one removes one thread from the pool for the duration, and the queue has no way to compensate.

rust
// compiles, runs, and starves the runtime async fn handler() -> String { std::thread::sleep(std::time::Duration::from_secs(2)); // blocks a worker "done".to_string() }
rust
// correct: yields the worker back to the executor async fn handler() -> String { tokio::time::sleep(std::time::Duration::from_secs(2)).await; "done".to_string() }

Reproduce it with a runtime that has one worker and two tasks:

rust
#[tokio::main(flavor = "current_thread")] async fn main() { let a = tokio::spawn(async { std::thread::sleep(std::time::Duration::from_millis(500)); }); let b = tokio::spawn(async { let t = std::time::Instant::now(); tokio::time::sleep(std::time::Duration::from_millis(10)).await; println!("timer took {:?}", t.elapsed()); // ~500ms, not 10ms }); let _ = tokio::join!(a, b); }

The timer is not broken; it could not be polled, because the only worker was inside std::thread::sleep. On a multi-thread runtime the same code looks healthier until as many tasks block as there are workers.

The escape hatch for blocking work:

rust
async fn read_config(path: &Path) -> std::io::Result<String> { let path = path.to_owned(); tokio::task::spawn_blocking(move || std::fs::read_to_string(path)).await? }

Key Comparison Table

Inside an async fnBlocks a workerUse instead
std::thread::sleepyestokio::time::sleep
std::fs::readyestokio::fs::read or spawn_blocking
reqwest::blockingyesreqwest async client
std::sync::Mutex guard across .awaityestokio::sync::Mutex
std::sync::Mutex guard, no .await insidenokeep it
CPU loop over 10 msyesspawn_blocking, or chunk and yield_now().await
futures::executor::block_onpanics.await
Escape hatchRuntimeCostUse for
spawn_blockinganythread from the blocking poolsync IO, FFI, CPU work
block_in_placemulti-thread onlymoves other tasks off the workerunavoidable blocking in place
yield_now().awaitanyreschedules the tasklong loops between chunks
dedicated thread + channelanyone OS threadcontinuous blocking work

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. A std::sync::Mutex across an .await

Two different symptoms, depending on where the guard lives. Held inside a future passed to tokio::spawn, the guard is !Send and the compiler refuses: future cannot be sent between threads safely. Held inside a plain .await in a current_thread runtime, it deadlocks instead.

rust
// deadlock risk: the guard is alive across the await let guard = state.lock().unwrap(); db.save(&*guard).await?; // other tasks waiting for this lock cannot proceed // fixed let snapshot = { state.lock().unwrap().clone() }; db.save(&snapshot).await?; // or, when the critical section really must await let guard = tokio_mutex.lock().await;

Cloning the small value out of the guard is usually better than an async mutex: it keeps the critical section synchronous and short.

2. spawn_blocking and its own ceiling

The blocking pool defaults to 512 threads and is separate from the worker pool, so it does not starve timers. It can still be exhausted: 600 concurrent blocking jobs queue behind the max_blocking_threads limit and the 601st waits, which looks like a hang in one code path.

rust
let runtime = tokio::runtime::Builder::new_multi_thread() .worker_threads(4) .max_blocking_threads(64) // explicit, not the 512 default .thread_keep_alive(Duration::from_secs(30)) .enable_all() .build()?;

Blocking tasks are not cancellable: dropping the JoinHandle detaches the work but does not stop it, which matters for a request that timed out while its blocking task continues to consume CPU.

3. CPU work, chunked

A 200 ms computation is too long for a worker. Either move it out or break it up so the executor can run other tasks between chunks.

rust
async fn score(items: &[Item]) -> Vec<f32> { let mut out = Vec::with_capacity(items.len()); for (i, item) in items.iter().enumerate() { out.push(heavy(item)); if i % 256 == 0 { tokio::task::yield_now().await; // let other tasks poll } } out }

yield_now costs a scheduling round trip; the chunk size should be large enough that the overhead disappears and small enough that latency stays bounded.

4. Detecting starvation before users report it

tokio-console shows per-task poll duration and busy time, and it needs the unstable flag at build time:

toml
# Cargo.toml tokio = { version = "1", features = ["full", "tracing"] }
bash
RUSTFLAGS="--cfg tokio_unstable" cargo run # then: tokio-console

Without the console, RuntimeMetrics gives the same signal as numbers: worker_total_busy_duration near 100% with low throughput is starvation, while high throughput means the work is simply CPU-bound and needs a bigger runtime.

5. block_in_place is not a general fix

block_in_place tells the runtime to move other tasks off this worker while the current one blocks. It requires the multi-thread runtime and panics on current_thread, which is exactly the runtime used in most tests — so a fix validated by #[tokio::test] can panic in production or the reverse.

rust
// multi-thread only tokio::task::block_in_place(|| expensive_sync_call());

spawn_blocking works on both flavours and is the safer default. block_in_place is for code that must keep its stack, such as a synchronous callback that cannot be moved.

6. Blocking in async tests

#[tokio::test] defaults to current_thread, so a single blocking call starves the test and it hangs instead of failing. Run the test on a multi-thread runtime, or with a longer timeout, when the code under test is expected to spawn.

rust
#[tokio::test(flavor = "multi_thread", worker_threads = 2)] async fn concurrent_handlers() { /* … */ }

Common Compilation/Runtime Mistakes & Version Gotchas

  • std::thread::sleep in async code. The single most common cause; it never yields and never warns.
  • reqwest::blocking inside a Tokio task. It creates its own runtime and can deadlock; use the async client.
  • A !Send guard held across .await. Compile error in spawn, deadlock without it.
  • spawn_blocking for everything. It moves the starvation to the blocking pool and adds thread-switch cost to work that would have been fine inline.
  • block_in_place in a current_thread runtime. Panics; tests use that runtime by default.
  • max_blocking_threads left at 512 with 1000 concurrent blocking jobs. Queueing that looks like a hang in one endpoint.
  • Detached blocking tasks after a timeout. The request is gone, the CPU work is not; account for it in capacity.

Related tools. Read a tokio-console export or a RuntimeMetrics snapshot as formatted JSON with the JSON formatter, compare two runtime configurations with the YAML to JSON converter before diffing them as text, and convert the timestamps in a slow-task log to local time with the timestamp converter.

Try matching browser tools

All tools

Small utilities that fit Rust work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Rust guides

More in Rust

All Rust guides

The guides filed next to this one in Rust, in library order.