Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 40 ยท Event Loop and Coroutines

Blocking the Event Loop and How to Avoid It

Learn how blocking calls freeze asyncio programs, measure event loop lag, chunk long work with sleep(0), offload to_thread or processes and use debug mode.

The single most common asyncio bug is not a syntax error. It is blocking the event loop: calling something slow without await, so every other task freezes until it returns. The program still produces correct results, but it behaves as if it were synchronous, and a web server would stop answering every user while one request sleeps.

This lesson teaches you to recognize blocking calls, to measure the damage with a tiny "lag monitor", and to fix the problem in three ways: use the async version of the call, break the work into chunks, or move it to a worker.

What counts as blocking

A call blocks the loop if the thread cannot do anything else until it finishes. Typical offenders:

Blocking call Async replacement
time.sleep(1) await asyncio.sleep(1)
requests.get(url) aiohttp or httpx.AsyncClient
open(...).read() on big or slow files aiofiles, or asyncio.to_thread
socket.recv() asyncio streams
subprocess.run(...) asyncio.create_subprocess_exec
long for loop of pure computing processes, NumPy, or chunking
sync database drivers async drivers, or to_thread

Small, quick operations (a dictionary lookup, a few microseconds of math) are fine. Rule of thumb: anything that can take more than a few milliseconds should not run directly on the loop.

On a normal computer time.sleep blocks the whole loop. This site's browser editor handles time.sleep specially and may let other tasks run during it, so the examples below block with a busy loop instead, which behaves like a long computation everywhere.

Measuring the damage: a lag monitor

A healthy loop wakes a short sleeper almost exactly on time. If it wakes late, something blocked the loop in between. This tiny monitor is a real production technique:

Python Detecting loop lag

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.

After busy_wait(0.3) the monitor reports a lag of about 0.3 seconds: for that long no other task could run. Frameworks export this number as a health metric. If it grows, something is blocking.

Fix 1: use the async version

When an async equivalent exists, use it. It is almost always the best fix, because the library cooperates with the loop. Changing time.sleep to asyncio.sleep is the simplest example, and the same idea applies to HTTP, databases and files.

Fix 2: chunk long computations

If you must compute in the loop, break the work into slices and await asyncio.sleep(0) between them, so other tasks get a turn. The result is the same but the loop stays responsive:

Python Yielding during long work

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.

Chunking suits moderate work. It does not make code faster and it adds overhead, so for serious number crunching use Fix 3.

Fix 3: move the work to a worker

await asyncio.to_thread(func, *args) runs a blocking function in a thread. It is perfect for blocking I/O libraries and for C extensions that release the GIL. For pure-Python CPU work, use a process pool with loop.run_in_executor (comparison lesson).

Python to_thread for blocking functions

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.

On a normal computer each call runs in its own worker thread and the loop keeps serving other tasks. On this site's editor there are no real threads, so the function runs inline; the code and results are the same, but the loop is not kept free here.

Debug mode: let Python tell you

Turn on debug mode while developing and asyncio reports slow callbacks, never-awaited coroutines and thread misuse. This script is read-only because the editor on this site does not implement the slow-callback report:

Python
import asyncio
import time


async def slow():
    time.sleep(0.3)


asyncio.run(slow(), debug=True)

On your computer, it logs a warning like:

TEXT
Executing <Task finished name='Task-1' coro=<slow() done, defined at app.py:5> result=None created at ...> took 0.301 seconds

Any step that runs longer than loop.slow_callback_duration (0.1 seconds by default) is reported along with the task that caused it. You can also enable debug mode with python -X dev or the environment variable PYTHONASYNCIODEBUG=1. Debug mode adds overhead, so it is not for production.

A checklist when the program feels slow

  1. Search your coroutines for time.sleep, requests, open().read(), subprocess.run, input().
  2. Check third-party libraries: is there an async variant, or does the call hide a blocking socket?
  3. Add a lag monitor, or run with debug mode, to find the culprit.
  4. Fix with async libraries, chunking or to_thread/process pools.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does time.sleep(2) do inside a coroutine?

    time.sleep blocks the thread, and the loop shares that thread. Use await asyncio.sleep(2).
  2. 2. How does a lag monitor detect blocking?

    If the loop is blocked, the sleeper resumes later than expected, and the difference is the lag.
  3. 3. Which is the best way to run a blocking third-party function from a coroutine?

    to_thread moves the blocking call to a worker thread so the loop can continue.
  4. 4. What does await asyncio.sleep(0) inside a long loop achieve?

    It yields control for one loop turn, so other tasks get to run, though it does not speed up the work itself.

Summary

  • A blocking call freezes every task, because they all share one thread.
  • Typical culprits: time.sleep, requests, sync file and database access, heavy loops.
  • Measure with a lag monitor; asyncio debug mode can also report slow steps.
  • Fix by using async libraries, chunking with await asyncio.sleep(0), or offloading with to_thread or a process pool.

Next: Creating tasks