Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 40 ยท Networking and Streams

Flow Control and Backpressure in asyncio

Understand backpressure in asyncio: why writer.drain() matters, how pause_writing and high-water marks work, and how bounded queues keep fast producers in check.

A fast sender talking to a slow receiver is a recipe for trouble. If the sender keeps producing data and nobody tells it to slow down, the data piles up in memory until the process is killed. Backpressure is the name for the signal that travels from the slow side back to the fast side and says "wait". asyncio has backpressure built into streams and queues; you only have to use it correctly.

This lesson shows the mechanism underneath writer.drain(), demonstrates the memory growth you get when you skip it, and then applies the same idea to queues and to your own pipelines. The demo uses a fake network link that drains at a fixed, slow speed, so you can watch the buffer.

Where the data waits

When you call writer.write(data), the bytes go into the transport's write buffer and the call returns immediately. The event loop moves bytes from the buffer to the operating system whenever the socket is writable. If the peer reads slowly, the socket stays full and the buffer in your process grows.

The transport has two thresholds, the high-water mark and the low-water mark (defaults: 64 KiB and 16 KiB):

  1. The buffer grows past the high-water mark: the transport calls the protocol's pause_writing().
  2. A StreamWriter remembers that it is paused. From now on await writer.drain() suspends your task.
  3. The buffer shrinks below the low-water mark: the transport calls resume_writing() and drain() returns.
sequenceDiagram
    participant P as Your task
    participant T as Transport buffer
    participant N as Slow network
    P->>T: write(chunk)
    T-->>P: buffer above high mark, pause_writing
    P->>T: await drain() (suspended)
    N->>T: sends bytes, buffer shrinks
    T-->>P: below low mark, resume_writing
    P->>T: drain() returns, write next chunk

drain() is the point where a fast producer is made to wait for a slow consumer.

Watching it happen

Below, SlowTransport sends only 10 bytes every 10 milliseconds and uses tiny thresholds (pause above 20 bytes, resume at 5 or less) so the effect is visible. We send 100 bytes twice: once with drain() after every write, and once without it.

Python With and without drain()

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.

Without drain() the whole 100 bytes sat in memory at once. With it, the buffer never grew past a few chunks, because the producer paused whenever the link was behind. Scale 100 bytes up to a 4 GB file and you can see why the habit matters.

You can tune the thresholds on a real connection with writer.transport.set_write_buffer_limits(high=..., low=...), and check the current backlog with writer.transport.get_write_buffer_size().

The reading side: pause_reading

The mirror image exists for incoming data. A StreamReader buffers what arrives. If your code reads slowly, the reader's buffer would grow, so when it holds more than twice its limit, the reader asks the transport to pause_reading(). The operating system's receive buffer then fills, TCP's own window shrinks to zero, and the sender is told to stop. You get end-to-end backpressure for free, as long as you actually await your reads and don't pile data up in your own lists.

The same idea with queues

Between your own tasks, the tool for backpressure is a bounded queue. asyncio.Queue(maxsize=n) makes await queue.put(item) wait when the queue already holds n items. A fast producer is held back by a slow consumer exactly like drain() does for a socket. An unbounded queue (the default, maxsize=0) has no backpressure and will happily eat all your memory. The queues chapter covers the details; here is the effect.

Python A bounded queue pushes back

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.

The log shows the producer racing ahead until the queue is full and then waiting for the consumer, never holding more than the limit.

Rules of thumb

  • Always await writer.drain() after write() when you send more than a small message, and certainly inside any loop.
  • Prefer bounded queues (maxsize greater than zero) for pipelines. Pick a size from how much latency or memory you can tolerate, not a huge number.
  • Reading in chunks with read(n) and processing each chunk keeps memory flat; calling read() with no argument loads everything.
  • When you forward data from one connection to another (a proxy), drain() on the outgoing writer is what slows the incoming reader. Write, drain, then read the next chunk.
  • Backpressure fails silently if any link in the chain buffers without limit. Check for unbounded lists, queues and gather calls over millions of items.

For the next topic, learn how to give up on slow peers with timeouts.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does "await writer.drain()" do when the transport's buffer is below the high-water mark?

    drain() only suspends the task while the writer is paused, that is, after the buffer has exceeded the high-water mark and before it falls below the low-water mark.
  2. 2. What happens to a loop that calls writer.write() many times without ever awaiting drain() while the peer is slow?

    write() never waits. Without drain() nothing slows the producer, so the buffer grows without limit.
  3. 3. How does asyncio.Queue(maxsize=3) provide backpressure?

    A full bounded queue suspends producers in "await put()" until a consumer takes an item.
  4. 4. Which pair of methods does a transport call on the protocol around the high and low water marks?

    pause_writing() is called when the buffer rises above the high-water mark, resume_writing() when it falls below the low-water mark.

Summary

  • write() only buffers; drain() is where a fast writer waits for a slow peer.
  • Transports call pause_writing() above the high-water mark and resume_writing() below the low-water mark.
  • Readers apply backpressure by pausing reads, which lets TCP slow the sender.
  • In your own pipelines use bounded asyncio.Queue(maxsize=n) so producers wait when consumers fall behind.

Next: Timeouts with wait_for and asyncio.timeout