• AI 技能
• AI 插件
• 人工智能

本指南聚焦 Boost.Asio（及 standalone Asio）在C++11–17 工具链下的异步编程方案，解决"没有co_await就不能优雅地写异步网络代码"这一核心痛点。内容以仓库中 pre-cpp20.md 为骨架，结合 SKILL.md 的版本底线与易错规则展开。读完你将掌握：如何在 C++11 下用completion handlers（回调）与stackful coroutines（asio::spawn+yield_context）写出与 C++20 协程风格等价的全双工、带超时、带帧协议的网络代码，并正确配置 CMake 构建。

为什么还需要 Pre-C++20 风格

C++20 的co_await让异步代码变得像同步代码一样可读，但现实是大量生产环境的工具链仍是 C++11/14/17，尤其是长期发行版（例如 Debian bookworm 内置 Boost 1.74，不支持awaitable_operators.hpp头文件）。正如 SKILL.md 所强调的：Asio 的 API 形态经历了三次演进（classicio_service→io_context→ C++20 coroutines），同一个任务在三种工具链上有三种"正确答案"，必须先确认目标 Boost 版本与 C++ 标准，再选择对应的编码风格。

关键认知是：不能使用co_await时，同一套 Asio 库（现代 Boost 或 standalone Asio）依然可用，改变的只是异步风格的写法。io_context、make_strand、bind_executor、steady_timer、ssl::stream、signal_set、async_read/async_write/async_read_until、缓冲区和resolver都是库特性而非语言特性，在协程风格与回调风格中完全一致，可直接按 coroutines.md 中的用法使用。

Pre-C++20 有两种主流风格：

1. Completion handlers（回调）：header-only、C++11 起可用、无额外依赖，是推荐的基准方案；
2. Stackful coroutines（asio::spawn+yield_context）：写法像co_await，但构建在 Boost.Coroutine/Boost.Context 之上，必须链接（非 header-only），详见下文构建差异。

C++20 → Pre-C++20 特性映射

在 C++11–17 环境下，以下 C++20 专属机制不可用：co_await/awaitable<T>、co_spawn、use_awaitable、||/&&的awaitable_operators、as_tuple与co_composed。原文档（pre-cpp20.md 中 "C++20 → pre-C++20 mapping" 一节）给出了完整的等价映射表：

理解这张表的关键在于：||与&&不是语言特性，而是协程风格的表达便利；在回调世界中没有并发的语法糖，只能靠定时器、共享计数和组合操作手工编排并发语义。

回调风格：全双工 + 写队列

回调风格下全双工的写队列规则与协程风格完全一致——单靠 strand 并不能阻止交错写入，必须用队列 + 在途标志强制同一时刻最多只有一个async_write。区别只在于用链式 handler 表达。同时必须在每一个 handler中捕获self = shared_from_this()以保持连接存活（pre-cpp20.md 中的核心示例）：

class connection : public std::enable_shared_from_this<connection> { tcp::socket socket_; asio::strand<asio::any_io_executor> strand_; // tcp::socket's executor is any_io_executor std::deque<std::string> outbox_; bool writing_ = false; char buf_[1024]; public: explicit connection(tcp::socket s) : socket_(std::move(s)), strand_(asio::make_strand(socket_.get_executor())) {} void start() { do_read(); } void send(std::string frame) { // call on the strand only outbox_.push_back(std::move(frame)); if (!writing_) do_write(); } private: void do_read() { auto self = shared_from_this(); socket_.async_read_some(asio::buffer(buf_), asio::bind_executor(strand_, // serialize handler execution this, self { if (ec) return; // self drops here → socket closes /* parse buf_[0..n]; call send() for replies */ do_read(); })); } void do_write() { // at most one async_write in flight writing_ = true; auto self = shared_from_this(); asio::async_write(socket_, asio::buffer(outbox_.front()), asio::bind_executor(strand_, this, self { if (ec) { writing_ = false; return; } outbox_.pop_front(); if (!outbox_.empty()) do_write(); else writing_ = false; })); } };

这段代码同时印证了 SKILL.md 中"最容易出错的三条规则"：

• strand 不序列化写入：strand 序列化的是 handler 的执行，不是整个组合操作的字节流。同一 strand 上两个在途的async_write仍会在线路上交错字节。全双工场景（读循环 + 并发推送/应答）需要每连接一个 strand并且一个带在途标志的出站队列；
• 缓冲区不拥有内存：asio::buffer()只是视图，底层存储必须存活到异步操作结束。回调风格下这些数据必须是成员变量而非函数局部变量；
• 连接必须比其 handler 存活更久：enable_shared_from_this+ 在每个 handler /co_spawn中捕获self。

Stackful 风格：spawn + yield_context

yield本身是一个完成令牌（completion token）：op(socket, ..., yield)会挂起直到操作完成并返回结果；错误默认抛出异常，也可用yield[ec]将其转为error_code。每条链应运行在每连接专属的 strand 上（pre-cpp20.md）：

asio::spawn(strand, // executor or strand self { // capture self for lifetime try { char data[1024]; for (;;) { std::size_t n = self->socket_.async_read_some(asio::buffer(data), yield); asio::async_write(self->socket_, asio::buffer(data, n), yield); } } catch (const std::exception&) { self->socket_.close(); } }, asio::detached); // completion token (3rd arg)

注意事项：

• 错误处理策略：默认抛boost::system::system_error（对应 C++20 风格默认行为）；yield[ec]不抛异常，显式检查ec，语义上等价于as_tuple(use_awaitable)；
• 生命周期：lambda 必须捕获self，与回调风格同样遵循"连接存活于所有异步链"原则；
• 第三个参数是完成令牌，asio::detached表示不关心协程的结果；
• 三参数形式spawn(ex, fn, token)需要Boost ≥ 1.80，旧版 Boost 只有两参数spawn(ex, fn)——这正是下文构建差异的关键点。

无||的超时实现：看门狗定时器

C++20 风格里read || timer一行就能实现"读超时竞争"。Pre-C++20 下没有这个语法糖，需要用独立的看门狗定时器替代：每次读到数据就重置定时器，第二条链等待定时器并在到期时关闭 socket，从而让在途的读操作以operation_aborted失败（pre-cpp20.md）：

// callback watchdog void arm_timeout() { timer_.expires_after(std::chrono::seconds(30)); auto self = shared_from_this(); timer_.async_wait(asio::bind_executor(strand_, this, self { if (!ec) socket_.close(); // fired → drop; reset cancels with ec })); } // call arm_timeout() again on every frame received to re-arm

两个容易踩坑的细节：

• 重置定时器会让在途的async_wait以operation_aborted完成——在空闲超时循环中这是"继续等待"的信号，不是错误（SKILL.md 的 Step 3 明确列出此规则）；真正的到期才以无错误代码完成并关闭 socket；
• 超时关闭 socket 使另一条链上的读操作收到operation_aborted，即实现了||的取消语义——这正是映射表中 "first-wins race" 的落地方案。

回调风格的多步读与周期性伴随任务

生命周期转移：协程局部变量 → 成员变量

这是回调风格最核心的心智转换：协程风格里co_await挂起时栈帧仍存活，局部缓冲区安全；回调风格里handler 运行在异步操作完成之后，此时函数局部变量早已析构，因此头部/正文缓冲区必须成为成员变量，否则就是悬垂引用（dangling）。同时遵循"帧协议必须用组合读"的规则——async_read恰好填满缓冲区，而async_read_some可能短读（pre-cpp20.md）：

// members, NOT locals — they must survive until the handler runs uint32_t len_be_; std::string body_; static constexpr std::uint32_t max_frame_size = 1U << 20; // protocol limit: 1 MiB void read_frame() { auto self = shared_from_this(); asio::async_read(socket_, asio::buffer(&len_be_, sizeof len_be_), asio::bind_executor(strand_, this, self { if (ec) return; const std::uint32_t frame_length = ntohl(len_be_); if (frame_length > max_frame_size) { boost::system::error_code ignored; socket_.close(ignored); // reject before allocation return; } body_.assign(static_cast<std::size_t>(frame_length), '\0'); asio::async_read(socket_, asio::buffer(body_), // read exactly N bytes asio::bind_executor(strand_, this, self { if (ec2) return; handle_frame(body_); // dispatch on type byte read_frame(); // next frame })); })); }

这里的max_frame_size上限是安全关键点：长度前缀来自不可信对端，先校验长度再分配内存，否则std::string(n, '\0')的 n 被攻击者控制会成为内存耗尽向量（SKILL.md 的 Security & Safety Notes 明确提示）。socket_.close(ignored)在分配前拒绝超限帧，正是防御性编程的正确顺序。

周期性伴随任务：自重新调度定时器

协程风格中一个 detached 的伴随协程可以靠标志位或cancellation_signal停止；回调风格中没有可停止的 detached 协程，做法是自重新调度（self-rescheduling）的定时器，停止方式为cancel()（pre-cpp20.md）：

void schedule_tick(std::string symbol, std::shared_ptr<asio::steady_timer> t) { t->expires_after(std::chrono::milliseconds(250)); auto self = shared_from_this(); t->async_wait(asio::bind_executor(strand_, this, self, symbol, t { if (ec) return; // cancelled on unsubscribe/close → stops send(make_tick(symbol)); // enqueue on the write queue schedule_tick(symbol, t); // reschedule itself })); } // start: keep one timer per subscription alive (e.g. in a map); stop: erase + t->cancel()

实现要点：

• 定时器以shared_ptr持有并常驻（例如存放在订阅 map 中），防止定时器对象在等待期间析构；
• 每条链都bind_executor(strand_)，确保与读/写链串行；
• 取消（cancel()）使在途async_wait以operation_aborted完成，if (ec) return即优雅终止——这再次体现"operation_aborted区分于真实错误"的全局规则。

构建差异：回调 vs Stackful spawn

回调风格除了 C++ 标准设置外无需额外依赖，CMake 配置如下（pre-cpp20.md）：

set(CMAKE_CXX_STANDARD 11) # or 14 / 17 set(CMAKE_CXX_EXTENSIONS OFF) # else CMake emits -std=gnu++NN, not literal -std=c++NN target_link_libraries(app PRIVATE Boost::headers Threads::Threads) target_compile_definitions(app PRIVATE BOOST_ERROR_CODE_HEADER_ONLY)

而 stackfulspawn额外依赖 Boost.Coroutine（其底层使用 Boost.Context），不是 header-only，必须显式链接：

find_package(Boost REQUIRED COMPONENTS coroutine) target_link_libraries(app PRIVATE Boost::coroutine) # pulls in Boost.Context

综合 SKILL.md 的版本底线，构建决策可以归纳为一张表：

两点补充说明：

• BOOST_ERROR_CODE_HEADER_ONLY必须在恰好一处定义（推荐在 CMake 的target_compile_definitions），因为 Boost 1.74 起Boost::system组件已是 header-only，无需链接Boost::system（这是 SKILL.md 常见错误表中专门列出的误配置）；
• 语言层面而非库层面的坑：chrono 字面量250ms/30s是C++14特性，真正的 C++11 构建应写作std::chrono::milliseconds(250)；
• -fcoroutines只用于 C++20 的co_await（GCC），Pre-C++20 风格不需要。

三种风格如何选择：决策建议

结合 SKILL.md 的风格选择矩阵（Step 1），Pre-C++20 场景下的推荐路径：

1. 先确认工具链：find_package(Boost)输出、dpkg -l libboost-dev、brew info boost、CMAKE_CXX_STANDARD，或直接询问——不要假设最新版本；
2. Boost ≥ 1.77 且 C++20：用协程风格（co_await+awaitable<T>），参考 coroutines.md；
3. Boost ≥ 1.74 且 C++11–17：优先回调风格（可移植基准），参考本指南对应的 pre-cpp20.md；
4. 确实需要同步式写法且 Boost ≥ 1.80：可选用 stackfulspawn+yield_context，但接受链接 Boost.Coroutine 的代价；
5. Boost 1.62–1.65（无io_context/make_strand/any_io_executor）：落入 classicio_service时代，参考 classic-boost.md。

无论选择哪种风格，SSL/TLS（ssl::stream<>）都是库特性，各风格通用——注意 SSL 流的所有异步操作都要求 strand 同步（见 ssl.md）。

提交前的自查清单

参考 SKILL.md 的 "Before you call it done" 清单，Pre-C++20 代码应逐项核对：

• 风格匹配目标 Boost 版本与 C++ 标准，且每个使用的 API 都满足其版本底线；
• 传给异步操作的每个缓冲区都存活到操作结束——回调风格禁止用局部变量，改用成员变量，杜绝悬垂string_view；
• 并发写时每 socket 至多一个在途async_write，由队列 + 标志强制执行；
• 共享对象上的每条异步链运行在同一 strand；每个 handler 都捕获self；
• 帧/定界读取使用组合读async_read/async_read_until，而非async_read_some；
• 每个操作都检查错误（回调的ec或yield[ec]），不吞错；
• 重设定时器或取消操作产生的operation_aborted与真实错误区分处理；
• CMake 包含标准设置、BOOST_ERROR_CODE_HEADER_ONLY（仅一处）、使用 stackfulspawn时链接Boost::coroutine；
• 实际编译验证——本仓库文档强调：版本底线只有真正构建过才算数。

• AI 技能
• AI 插件
• 人工智能