async_read_until (12 个重载中的第 8 个)

启动一个异步操作，将数据读取到 streambuf 中，直到函数对象指示匹配。

template<
    typename AsyncReadStream,
    typename Allocator,
    typename MatchCondition,
    typename ReadToken = default_completion_token_t<        typename AsyncReadStream::executor_type>>
DEDUCED async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    MatchCondition match_condition,
    ReadToken && token = default_completion_token_t< typename AsyncReadStream::executor_type >(),
    constraint_t< is_match_condition< MatchCondition >::value >  = 0);

此函数用于将数据异步读取到指定的 streambuf 中，直到用户定义的匹配条件函数对象应用于 streambuf 中包含的数据时，指示成功匹配。它是异步操作的启动函数，并始终立即返回。异步操作将继续，直到以下条件之一为真

匹配条件函数对象返回一个 std::pair，其中第二个元素的值为 true。
发生错误。

此操作通过零次或多次调用流的 async_read_some 函数来实现，被称为组合操作。如果匹配条件函数对象已经指示匹配，则此异步操作立即完成。程序必须确保流在操作完成之前不执行其他读取操作（例如 async_read、async_read_until、流的 async_read_some 函数或任何其他执行读取的组合操作）。

参数

s

要从中读取数据的流。该类型必须支持 AsyncReadStream 概念。

b

数据将读取到其中的 streambuf 对象。

match_condition

用于确定是否存在匹配的函数对象。函数对象的签名必须是

pair<iterator, bool> match_condition(iterator begin, iterator end);

其中 iterator 表示类型

buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>

迭代器参数 begin 和 end 定义要扫描的字节范围，以确定是否存在匹配项。返回值的 first 成员是一个迭代器，标记匹配函数已消耗的字节的末尾之后的位置。此迭代器用于计算匹配条件的任何后续调用中的 begin 参数。如果找到匹配项，返回值的 second 成员为 true，否则为 false。

token

将用于生成完成处理程序的完成令牌，该处理程序将在读取完成时调用。潜在的完成令牌包括 use_future, use_awaitable, yield_context, 或具有正确完成签名的函数对象。完成处理程序的函数签名必须是

void handler(
  // Result of operation.
  const boost::system::error_code& error,

  // The number of bytes in the streambuf's get
  // area that have been fully consumed by the
  // match function. O if an error occurred.
  std::size_t bytes_transferred
);

无论异步操作是否立即完成，完成处理程序都不会从此函数内部调用。在立即完成时，处理程序的调用将以等效于使用 async_immediate 的方式执行。

备注

在成功的 async_read_until 操作之后，streambuf 可能包含超出与函数对象匹配的其他数据。应用程序通常会将该数据留在 streambuf 中，以供后续的 async_read_until 操作检查。

完成签名

void(boost::system::error_code, std::size_t)

备注

is_match_condition 类型特征的默认实现对于具有 result_type typedef 的函数指针和函数对象评估为 true。它必须针对其他用户定义的函数对象进行专门化。

示例

异步读取数据到 streambuf 中，直到遇到空格

typedef boost::asio::buffers_iterator<
    boost::asio::streambuf::const_buffers_type> iterator;

std::pair<iterator, bool>
match_whitespace(iterator begin, iterator end)
{
  iterator i = begin;
  while (i != end)
    if (std::isspace(*i++))
      return std::make_pair(i, true);
  return std::make_pair(i, false);
}
...
void handler(const boost::system::error_code& e, std::size_t size);
...
boost::asio::streambuf b;
boost::asio::async_read_until(s, b, match_whitespace, handler);

异步读取数据到 streambuf 中，直到找到匹配的字符

class match_char
{
public:
  explicit match_char(char c) : c_(c) {}

  template <typename Iterator>
  std::pair<Iterator, bool> operator()(
      Iterator begin, Iterator end) const
  {
    Iterator i = begin;
    while (i != end)
      if (c_ == *i++)
        return std::make_pair(i, true);
    return std::make_pair(i, false);
  }

private:
  char c_;
};

namespace asio {
  template <> struct is_match_condition<match_char>
    : public boost::true_type {};
} // namespace asio
...
void handler(const boost::system::error_code& e, std::size_t size);
...
boost::asio::streambuf b;
boost::asio::async_read_until(s, b, match_char('a'), handler);

单次操作取消

此异步操作支持以下 cancellation_type 值的取消

cancellation_type::terminal
cancellation_type::partial

如果 AsyncReadStream 类型的 async_read_some 操作也支持它们。