Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 40 ยท Async Libraries and Patterns

Running Blocking Code from asyncio

Learn why blocking calls freeze the asyncio event loop, how to offload them with asyncio.to_thread, run_in_executor and process pools, and how to chunk CPU-bound work.

asyncio runs all your coroutines on one thread. That is why it is so light, and also why it has one golden rule: never block the event loop. A coroutine that calls time.sleep(5), requests.get(...), reads a huge file synchronously or crunches numbers for two seconds does not just slow itself down. It freezes every other task, every open connection and every timer until it returns.

This lesson shows how to see the problem, and what to do about it: hand blocking work to a thread (asyncio.to_thread, run_in_executor), to another process for CPU-heavy work, or break it into cooperative chunks.

Browser limitation. The lesson editor runs Python inside a browser page, where there are no operating-system threads or processes. In this environment asyncio.to_thread() runs the function inline, so it gives the right results but no real parallelism. The examples that demonstrate blocking and cooperative chunking run for real here; for the thread-pool examples, run them on your own computer to see the speed-up. The text says which is which.

What blocking looks like

A heartbeat task counts a beat every 10 ms. We block the loop with a busy wait (it holds the thread exactly like a blocking network or disk call would), and then wait politely with await asyncio.sleep. On a normal computer time.sleep(0.3) has the same effect as the busy wait; the browser's Python is special-cased to pause politely, so the demo uses a loop instead.

Python Blocking freezes every other task

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

While the busy wait held the thread, the heartbeat could not run even once. During await asyncio.sleep it ran many times. In a server, those 0.3 seconds would be added to every other request in flight.

Typical hidden blockers: requests, urllib, synchronous database drivers, open().read() of big files, subprocess.run, json.loads on huge text, image or data processing, time.sleep, password hashing such as bcrypt, and plain heavy loops.

Solution 1: asyncio.to_thread (Python 3.9+)

await asyncio.to_thread(func, *args, **kwargs) runs an ordinary function in a worker thread and gives you its result when it finishes. The event loop keeps running in the meantime, and the current context variables are copied into the thread.

Python
import asyncio, requests

def download(url):
    return requests.get(url, timeout=10).text      # blocking library

async def main():
    pages = await asyncio.gather(
        asyncio.to_thread(download, "https://example.org/a"),
        asyncio.to_thread(download, "https://example.org/b"),
    )

Both downloads run in separate threads at the same time. This works well for I/O-bound blocking code, because Python releases the GIL while a thread waits for the network or disk.

Here is the API in action. It returns correct results in the browser as well (inline, as noted), so you can study the shape of the code:

Python to_thread keeps the same call shape

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice the context variable request_id was visible inside the function: to_thread copies the context for you, which run_in_executor does not.

Solution 2: run_in_executor

loop.run_in_executor(executor, func, *args) is the older, more flexible API behind to_thread. The first argument chooses which executor to use; None means the loop's default ThreadPoolExecutor. It does not accept keyword arguments, so use functools.partial.

Python
from concurrent.futures import ProcessPoolExecutor
from functools import partial

loop = asyncio.get_running_loop()

# I/O-bound: the default thread pool
text = await loop.run_in_executor(None, read_big_file, path)

# CPU-bound: a process pool sidesteps the GIL
with ProcessPoolExecutor() as pool:
    result = await loop.run_in_executor(pool, partial(crunch, rows, mode="fast"))

Which pool?

Work Use Why
Blocking network or disk I/O threads (to_thread) the GIL is released while waiting
Heavy pure-Python computation ProcessPoolExecutor separate processes use several CPU cores
Calls into NumPy, hashing, compression often threads many C extensions release the GIL
Short, quick functions (under 1 ms) just call them handing off costs more than it saves

Functions sent to a process pool, and their arguments, must be picklable (module-level functions, not lambdas), and a process pool needs the if __name__ == "__main__": guard on some platforms. You can size the default thread pool with loop.set_default_executor(ThreadPoolExecutor(max_workers=32)).

Solution 3: cooperative chunking

When the work is CPU-bound pure Python and you cannot use threads or processes (or you are in a browser), you can make the loop breathe by yielding control every so often with await asyncio.sleep(0). This does not speed the calculation up, but it lets other tasks run between chunks. This example really runs in the browser:

Python Yielding control during a long computation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Both versions give the same answer. The difference is that the cooperative one let the heartbeat run while it worked. Pick the chunk size so that each slice takes only a few milliseconds.

Pitfalls

  • Threads are not cancellable. Cancelling await asyncio.to_thread(...) abandons the wait, but the function keeps running in its thread until it ends. Add your own stop flag (a threading.Event) for long jobs, and see cancelling tasks.
  • Thread safety. The function runs in another thread, so do not touch asyncio objects from it directly. To call back into the loop use loop.call_soon_threadsafe(...) or asyncio.run_coroutine_threadsafe(coro, loop).
  • Thread pool size. The default pool has min(32, cpu_count + 4) threads. More blocking calls than that queue up. A semaphore (rate limiting) makes the limit explicit.
  • Prefer a native async library (httpx, aiohttp, asyncpg, aiofiles) when one exists; see async HTTP clients. Threads are the bridge for libraries that have no async version.
  • Detect it. Turning on debug mode logs any callback that holds the loop for over 100 ms, which finds accidental blocking calls fast.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to other tasks while a coroutine runs time.sleep(2)?

    asyncio uses one thread. A blocking call holds it, so nothing else on the loop can run.
  2. 2. Which is the right tool for a blocking HTTP call made with the synchronous requests library?

    to_thread runs the blocking function in a worker thread and lets the loop continue. requests.get is not a coroutine, so it cannot be awaited directly.
  3. 3. Which executor suits heavy pure-Python number crunching that should use several CPU cores?

    Threads share the GIL, so pure-Python CPU work does not run in parallel in them. Separate processes do.
  4. 4. You cancel "await asyncio.to_thread(slow_function)". What happens to slow_function?

    Python threads cannot be force-stopped. Only the waiting coroutine is cancelled, so long jobs need their own stop flag.

Summary

  • One blocking call freezes the whole event loop; always keep coroutines non-blocking.
  • Use asyncio.to_thread() (or run_in_executor) for blocking I/O, a ProcessPoolExecutor for CPU-bound Python, and cooperative chunking with await asyncio.sleep(0) when neither is possible.
  • Threads cannot be cancelled, are not safe to share asyncio objects with, and come in limited numbers.
  • Prefer a native async library when there is one.

Next: Async HTTP clients and calling APIs