# Implementing Backpressure with ASIO Buffered Stream: A Complete Guide > Master ASIO's buffered_stream backpressure. Learn how fixed-size buffers manage network flow, pended writes, and paused reads for robust C++ networking. - Repository: [chriskohlhoff/asio](https://github.com/chriskohlhoff/asio) - Tags: how-to-guide - Published: 2026-07-11 --- **ASIO's `buffered_stream` provides automatic backpressure by interposing fixed-size memory buffers between your application and the underlying socket, causing `async_write_some` operations to pend when the write buffer is full and pausing network reads when the read buffer reaches capacity.** The chriskohlhoff/asio repository provides sophisticated stream abstractions that simplify flow control in high-performance networking applications. Implementing backpressure with ASIO buffered stream prevents fast producers from overwhelming slow consumers by leveraging configurable memory buffers that throttle data flow automatically. ## How Backpressure Works in `buffered_stream` ASIO's `buffered_stream` family creates an in-memory buffer layer between user-level operations and the underlying OS socket. This architecture absorbs data bursts and provides natural flow control through buffer capacity limits. ### Write Buffer Mechanics (`buffered_write_stream`) The write buffer, implemented in [`include/asio/buffered_write_stream.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/buffered_write_stream.hpp), holds outgoing data before it reaches the network. When an application calls `async_write_some`, data copies into this internal buffer. If the buffer reaches its configured capacity, subsequent write operations remain pending until `async_flush` (or automatic flushing) creates space by transferring data to the underlying socket. This mechanism forces the producer to wait for the network to drain, creating **write-side backpressure**. ### Read Buffer Mechanics (`buffered_read_stream`) The read buffer, defined in [`include/asio/buffered_read_stream.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/buffered_read_stream.hpp), stores pre-fetched incoming data via the `fill` and `async_fill` functions. When the consumer reads slower than the network delivers, the read buffer fills to capacity and additional network reads pause automatically. This prevents unlimited data accumulation in memory and propagates **read-side backpressure** upstream to the sender. ### Combined Interface (`buffered_stream`) The `buffered_stream` class declared in [`include/asio/buffered_stream.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/buffered_stream.hpp) combines both buffers into a single BidirectionalStream interface. It exposes `async_flush` for explicit write buffer control and `in_avail()` for monitoring how much data sits in the read buffer, allowing applications to implement sophisticated flow-control policies. ## Implementation Examples ### Basic TCP Buffered Stream Setup Wrap a `tcp::socket` with a buffered stream to enable automatic backpressure. The constructor accepts separate sizes for the read and write buffers: ```cpp #include #include #include using asio::ip::tcp; using asio::buffered_stream; void setup_buffered_stream(asio::io_context& io_context) { tcp::socket socket(io_context); // Create buffered stream with 8KB read and write buffers buffered_stream buf_stream( std::move(socket), 8 * 1024, // read buffer size 8 * 1024 // write buffer size ); std::string msg = "Hello, world!"; // Write data into the buffer; completes when data is accepted, not sent asio::async_write(buf_stream, asio::buffer(msg), [&](const asio::error_code& ec, std::size_t /*bytes*/) { if (!ec) { // Explicitly flush to underlying socket buf_stream.async_flush( [&](const asio::error_code& ec2, std::size_t flushed) { // flushed contains bytes actually sent to peer }); } }); } ``` The write buffer caps outstanding data at 8KB. If the application attempts to write more than this capacity, the operation queues until space becomes available. ### Explicit Flush Control for Backpressure For fine-grained control over when data actually hits the wire, configure a small buffer and manage flushes manually: ```cpp void demonstrate_backpressure(asio::io_context& io_context) { tcp::socket socket(io_context); // Small 1KB buffers to illustrate backpressure buffered_stream small_buf( std::move(socket), 1024, 1024 ); // Producer sends 100 chunks of 512 bytes each for (int i = 0; i < 100; ++i) { std::string chunk(512, 'x'); asio::async_write(small_buf, asio::buffer(chunk), [&](const asio::error_code& ec, std::size_t) { // Handler invoked when data enters buffer }); // After two chunks (1KB), buffer is full // Next write will pend until we flush if (i % 2 == 1) { small_buf.async_flush( [&](const asio::error_code& ec, std::size_t) { // Only continue after network drain }); } } } ``` With only 1KB of write buffer space, the producer stalls every two iterations, waiting for the network to drain the buffer before accepting more data. ### Monitoring Read-Side Pressure Use `in_avail()` to detect when the consumer is falling behind the producer: ```cpp void monitor_backpressure(buffered_stream& buf_stream) { char read_buf[1024]; buf_stream.async_read_some( asio::buffer(read_buf), [&](const asio::error_code& ec, std::size_t n) { if (!ec) { // Process n bytes... std::size_t pending = buf_stream.in_avail(); if (pending > 4096) { // Read buffer contains >4KB unread data // Next network read automatically paused // Application can pause processing or signal upstream } } } ); } ``` The `in_avail()` method returns the number of bytes currently stored in the read buffer, providing visibility into ingestion pressure. ## Configuration and Buffer Sizing The constructor signature in [`include/asio/buffered_stream.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/buffered_stream.hpp) accepts `std::size_t` parameters for both read and write storage: ```cpp buffered_stream stream( Stream&& stream, std::size_t read_buffer_size, std::size_t write_buffer_size ); ``` Size these buffers according to your application's latency and bandwidth requirements. Larger buffers accommodate burstier traffic but increase memory usage and delay backpressure signals. Smaller buffers minimize latency and memory footprint but may stall producers more frequently. The underlying storage implementation in [`include/asio/detail/buffered_stream_storage.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/detail/buffered_stream_storage.hpp) manages the circular buffer memory. ## Summary - **`buffered_stream`** combines read and write buffers from `buffered_read_stream` and `buffered_write_stream` to provide automatic flow control. - **Write-side backpressure** occurs when the write buffer fills, causing `async_write_some` operations to pend until `async_flush` drains the buffer to the socket. - **Read-side backpressure** happens when the read buffer reaches capacity, automatically pausing network reads until the application consumes data via `async_read_some`. - **Explicit control** through `async_flush` and `in_avail()` allows applications to implement custom flow-control policies beyond the automatic buffer limits. - **Buffer sizing** directly impacts backpressure latency and memory usage, requiring tuning based on specific workload characteristics. ## Frequently Asked Questions ### What is the difference between `buffered_stream` and raw socket operations? Raw socket operations write directly to the kernel send buffer or read directly from the kernel receive buffer, providing no mechanism to pause the application when it produces or consumes data too quickly. The `buffered_stream` adds an intermediate memory layer with configurable limits, allowing the ASIO io_context to throttle operations by completing handlers only when buffer space is available, effectively implementing backpressure at the application level. ### How do I choose the right buffer sizes for my application? Select buffer sizes based on the throughput mismatch between your producer and consumer. If the producer generates data much faster than the network can transmit, use a smaller write buffer (1-4KB) to apply backpressure quickly and prevent excessive memory growth. For high-latency networks where you want to batch data for efficiency, use larger buffers (64-256KB) to absorb round-trip delays. The unit tests in [`src/tests/unit/buffered_stream.cpp`](https://github.com/chriskohlhoff/asio/blob/main/src/tests/unit/buffered_stream.cpp) demonstrate behavior across various buffer sizes. ### When should I call `async_flush` manually versus letting the library handle it? Call `async_flush` manually when you need to ensure data reaches the peer before proceeding, such as when implementing request-response protocols or when you need to trigger immediate backpressure evaluation. The library automatically flushes the write buffer when it reaches capacity during write operations, but explicit flushing provides finer control over when the application yields to the network layer. ### Can `buffered_stream` be used with SSL or other stream layers? Yes, `buffered_stream` is a template that accepts any type meeting the Stream requirements, including `asio::ssl::stream`. This allows you to add buffering and backpressure to encrypted connections. The buffer sits between your application code and the SSL stream, which then sits above the TCP socket, creating a layered architecture where each level can apply its own flow control policies.