[/
    Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/boostorg/beast
]

[section 编写组合操作]

异步操作通过调用一个自由函数或成员函数来启动，该函数被称为异步[发起函数]。发起函数接收操作相关的参数以及一个 __CompletionToken__ 完成令牌。该令牌可以是一个完成处理器，也可以是一种用于定义调用方如何获知异步操作结果的方式。网络库提供 __use_future__ 和 __yield_context__ 这两种特殊令牌，分别用于支持 future 和协程。这种自定义返回值及完成通知方式的机制被称为 __N3747__ 中描述的通用异步模型，并已内置到 __NetTS__ 中。以下是一个发起函数的示例，该函数用于从流中读取一行数据并将其回显回去。下一节将进一步开发此函数：

[example_core_echo_op_1]

[tip
    该发起函数通过左值引用接收动态缓冲区，
    instead of by rvalue-reference as specified in networking. An explanation
    for this difference may be found in
    [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1100r0.html [P1100R0] Efficient composition with DynamicBuffer].
]
使用 Beast 的开发者可以复用库中的基本组件，来创建自己的发起函数。这些发起函数会在执行一系列中间异步操作之后，最终调用一个完成处理器。发起函数所产生的这一系列中间动作，被称为 [组合操作]。为确保良好的互操作性和行为的一致性，__Asio__ 对组合操作的实现方式提出了一些要求。以下提供的类和函数，可以帮助开发者更轻松地编写发起函数及其对应的组合操作：

[table 异步辅助函数
[[名称][描述]]
[[
    [link beast.ref.boost__beast__async_base `async_base`]
    [link beast.ref.boost__beast__stable_async_base `stable_async_base`]
][该类作为基类，专门用于编写以中间完成处理器形式表达的组合异步操作。使用它，可以避免编写大量用于传递关联执行器和关联分配器的样板代码。
]]
[[
    [link beast.ref.boost__beast__allocate_stable `allocate_stable`]
][对于需要为临时对象提供稳定存储的组合操作算法，可以使用此函数。该函数通过最终完成处理器所关联的分配器来分配稳定存储所需的内存。它会在最终完成处理器被调用之前，或者中间完成处理器被销毁时，自动销毁这些临时对象。
]]
[[
    [link beast.ref.boost__beast__bind_handler `bind_handler`]
][该函数用于创建一个新的处理器。当这个新处理器被调用时，它会使用预先绑定的参数列表去调用原始的处理器。调用时传入的参数，会替换掉绑定列表中的占位符；而那些没有对应占位符的参数，则会被悄悄丢弃。

传入的处理器和参数，都会被转发给返回的新处理器。这个新处理器的关联分配器和关联执行器，与原始处理器完全相同。
]]
[[
    [link beast.ref.boost__beast__bind_front_handler `bind_front_handler`]
][该函数用于创建新处理器。调用该新处理器时，系统会对原始处理器进行调用，并同时传入绑定参数列表以及调用参数列表。调用参数列表可位于参数列表的前端或后端。该函数不支持占位符。

传入的处理器与参数被转发至返回的新处理器。该新处理器的关联分配器及关联执行器均与原始处理器保持一致。
]]
[[
    [link beast.ref.boost__beast__saved_handler `saved_handler`]
][该包装类用于安全存储完成处理器，以便后续调用。通过该机制，实现方可以对操作进行“暂停”，直到满足特定条件后再继续执行。
]]
]

[include 7a_echo.qbk]
[include 7b_detect_ssl.qbk]

[endsect]