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.

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.
// 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()
}// 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:
#[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:
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 fn | Blocks a worker | Use instead |
|---|---|---|
std::thread::sleep | yes | tokio::time::sleep |
std::fs::read | yes | tokio::fs::read or spawn_blocking |
reqwest::blocking | yes | reqwest async client |
std::sync::Mutex guard across .await | yes | tokio::sync::Mutex |
std::sync::Mutex guard, no .await inside | no | keep it |
| CPU loop over 10 ms | yes | spawn_blocking, or chunk and yield_now().await |
futures::executor::block_on | panics | .await |
| Escape hatch | Runtime | Cost | Use for |
|---|---|---|---|
spawn_blocking | any | thread from the blocking pool | sync IO, FFI, CPU work |
block_in_place | multi-thread only | moves other tasks off the worker | unavoidable blocking in place |
yield_now().await | any | reschedules the task | long loops between chunks |
| dedicated thread + channel | any | one OS thread | continuous 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.
// 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.
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.
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:
# Cargo.toml
tokio = { version = "1", features = ["full", "tracing"] }RUSTFLAGS="--cfg tokio_unstable" cargo run
# then: tokio-consoleWithout 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.
// 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.
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn concurrent_handlers() { /* … */ }Common Compilation/Runtime Mistakes & Version Gotchas
std::thread::sleepin async code. The single most common cause; it never yields and never warns.reqwest::blockinginside a Tokio task. It creates its own runtime and can deadlock; use the async client.- A
!Sendguard held across.await. Compile error inspawn, deadlock without it. spawn_blockingfor everything. It moves the starvation to the blocking pool and adds thread-switch cost to work that would have been fine inline.block_in_placein acurrent_threadruntime. Panics; tests use that runtime by default.max_blocking_threadsleft 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 toolsSmall utilities that fit Rust work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Rust guides
All Rust guidesRust: Future Cannot Be Sent Between Threads Safely in Tokio
spawn needs Send + 'static, and any non-Send value alive across an await breaks it. Shorten the guard, switch the lock, or move the work to a LocalSet.
Rust Unsafe: Raw Pointers, FFI Bindings, and Soundness Invariants
What unsafe actually unlocks, the five soundness contracts behind raw pointers, and the FFI rules for repr(C), CString and unwinding.
Rust Pin and Unpin: Memory Pinning, Self-Referential Structs, and Futures
Why a future must not move after polling starts, what Unpin opts out of, and how Box::pin, pin! and map_unchecked_mut express that guarantee.
Rust Arrays and Slices: Fixed Arrays, &[T] Fat Pointers, and DSTs
An array carries its length in its type; a slice carries it in the pointer. The split_at_mut, chunks and TryFrom patterns that follow from that.
More in Rust
All Rust guidesThe guides filed next to this one in Rust, in library order.