Boost.Asio / standalone Asio

Overview

Write async C++ networking code that compiles on the user's Boost, not the newest one. Asio's API changed shape three times (classic ioservice → iocontext → C++20 coroutines) and most Asio code on the internet is from the first era, so pick the style from the toolchain first, then follow that style's reference file.

References: Boost.Asio · standalone Asio

Asio's API changed shape three times, so the same task has three correct answers depending on the Boost version in front of you. This skill makes the agent establish that version first, then apply the rules that are genuinely easy to get wrong — strand versus write serialization, buffer and connection lifetime, composed reads for framing — and finally check its own output against a list before calling it done.

When to Use This Skill

• Use when writing or reviewing async C++ networking code with Boost.Asio or standalone Asio: TCP/UDP servers and clients, SSL/TLS streams, timers, resolvers.
• Use when the code involves iocontext, ioservice, cospawn, awaitable, asyncread, asyncwrite, strand, asio::spawn, yieldcontext, or completion-handler callbacks.
• Use when the target toolchain is old: an older Boost or a pre-C++20 standard, where coroutine examples will not compile.
• Use when async code compiles but misbehaves: interleaved writes, dangling buffers, sockets closing early, operation_aborted treated as an error.

Step 1: pick the style (do this before writing code)

Determine the Boost (or Asio) version and the C++ standard actually in use — findpackage(Boost) output, dpkg -l libboost-dev, brew info boost, CMAKECXX_STANDARD, or ask. Do not assume the newest.

SSL/TLS in any style: [references/ssl.md](references/ssl.md). CMake for any style: [references/build.md](references/build.md).

iocontext, makestrand, bindexecutor, steadytimer, signalset, asyncread/asyncwrite/asyncread_until, buffers and resolver are library features — identical in the coroutine and callback styles. Only the suspension mechanism differs.

Step 2: version floors (verified by compiling, not from docs)

Reach for one of these and the build breaks on older distros:

Distro floors that bite: Debian bookworm ships Boost 1.74 (no awaitableoperators.hpp — #include fails outright), Ubuntu 20.04 ships 1.71 (no anyio_executor), Debian 9 ships 1.62.

Language, not library: the chrono literals 250ms / 30s are C++14. For a true C++11 build write std::chrono::milliseconds(250).

Step 3: the rules that are actually easy to get wrong

A strand does not serialize writes. A strand serializes handler execution, not whole composed operations. Two asyncwrites in flight on the same strand still interleave bytes on the wire. Full-duplex (a read loop plus concurrent pushes/replies) needs a per-connection strand and an outbound queue with an in-flight flag, so at most one asyncwrite exists at a time. This is the single most common wrong answer about Asio.

Buffers do not own memory. asio::buffer() is a view. Storage must outlive the operation: coroutine locals are fine across co_await in the same frame; in callback style the same data must become a member, not a local.

Connections must outlive their handlers. enablesharedfromthis, and capture self in every cospawn / handler — read loop, write loop, and each timer.

Frame with composed reads. asyncread (fills the buffer exactly) for a length prefix and then the body; never asyncread_some, which returns short.

Wrap astuple. Always astuple(useawaitable). Bare astuple resolves against the operation's default token and compiles in some contexts, fails in others.

asyncaccept(makestrand(...)) changes two things: it forces an explicit completion token back on the call, and the accepted socket is basicstreamsocket<tcp, strand<...>>, not tcp::socket. Take it by value or with auto — binding it to tcp::socket& will not compile.

Re-arming a timer resolves the pending wait with operation_aborted. In an idle-timeout loop that is the signal to keep waiting, not an error.

GCC needs -fcoroutines for the C++20 style, and header-only Boost needs BOOSTERRORCODEHEADERONLY defined in exactly one place (CMake).

Common mistakes

Boost.Asio vs standalone Asio

Same author, same API — namespace and includes differ.

Support both with a shim, then use net:: throughout:

#ifdef USE_STANDALONE_ASIO
  #include <asio.hpp>
  namespace net = asio;
  using error_code = asio::error_code;
#else
  #include <boost/asio.hpp>
  namespace net = boost::asio;
  using error_code = boost::system::error_code;
#endif
namespace ssl = net::ssl;
using tcp = net::ip::tcp;

Before you call it done

Check the code you just wrote against this list:

• Style matches the target Boost version and C++ standard (Step 1), and every API used clears its floor (Step 2).
• Every buffer passed to an async op outlives that op — no callback locals, no dangling string_view.
• At most one async_write per socket in flight, enforced by a queue + flag, if anything writes concurrently with reading.
• Every async chain on a shared object runs on the same strand; self captured in every handler and co_spawn.
• Framing / delimited reads use composed asyncread / asyncread_until.
• Errors are handled, not swallowed: astuple(useawaitable) destructured, or the callback's ec checked, on every op.
• operation_aborted distinguished from real errors wherever a timer is re-armed or an op is cancelled.
• Acceptor sets reuse_address; shutdown path closes the acceptor and drains sessions.
• CMake has the standard, -fcoroutines for GCC (C++20 only), BOOSTERRORCODEHEADERONLY in one place, and Boost::coroutine only if using stackful spawn.
• It compiles. Build it — most of the mistakes above are compile-time, and the version floors are only real once tested.

Worked examples

Three CI-verified implementations of the same full-duplex framed-protocol server, one per style — copy from the one matching Step 1. Paths are relative to this skill directory; if only the skill was installed, they are at https://github.com/alexprivalov/boost-asio-skill/tree/main/examples.

• ../../examples/market-data-feed/ — C++20 coroutines (Boost 1.77+; verified 1.83–1.90)
• ../../examples/market-data-feed-precpp20/ — callbacks, C++11-clean (verified Boost 1.74+, incl. Windows/MSVC)
• ../../examples/market-data-feed-classic/ — classic io_service (verified back to Boost 1.62 / Debian 9)

Official documentation

• Overview: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/overview.html
• Reference: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference.html
• Examples: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/examples.html

Limitations

• This skill does not replace compiling and testing against the target toolchain. The version floors it documents are only real once built — build the code.
• It does not cover Boost.Beast (HTTP/WebSocket), io_uring backends, or UDP multicast specifics.
• Stop and ask when the Boost version and C++ standard cannot be determined; the style choice depends on them.

Security & Safety Notes

• Read-only guidance: this skill contains no shell commands, network fetches, credentials, or mutation instructions. The commands it names (dpkg -l libboost-dev, brew info boost) are local version queries.
• Networking code it produces accepts untrusted input. Validate length prefixes before allocating (std::string body(n, 0) with an attacker-controlled n is a memory-exhaustion vector — cap it), and verify peer certificates when using TLS rather than disabling verification to make a handshake pass.

Related Skills

• @cpp-pro — general modern C++ idioms; this skill assumes them and adds the Asio-specific rules.