Boost C++ 库

……是全球最受推崇、设计最精良的 C++ 库项目之一。 Herb SutterAndrei Alexandrescu, 《C++ 编码标准》

async_read_until (12 个重载中的第 5 个) - Boost C++ 函数库
PrevUpHomeNext

启动一个异步操作,将数据读取到 streambuf 中,直到它包含指定的定界符。

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadToken = default_completion_token_t<        typename AsyncReadStream::executor_type>>
DEDUCED async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    char delim,
    ReadToken && token = default_completion_token_t< typename AsyncReadStream::executor_type >());

此函数用于将数据异步读取到指定的 streambuf 中,直到 streambuf 的 get 区域包含指定的定界符。它是 异步操作 的发起函数,并且总是立即返回。异步操作将继续进行,直到满足以下条件之一:

  • streambuf 的 get 区域包含指定的定界符。
  • 发生错误。

此操作是通过零次或多次调用流的 async_read_some 函数来实现的,并被称为 复合操作。如果 streambuf 的 get 区域已包含定界符,则此异步操作将立即完成。程序必须确保在操作完成之前,流不执行任何其他读取操作(例如 async_read、async_read_until、流的 async_read_some 函数,或任何其他执行读取的复合操作)。

参数

s

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

b

一个 streambuf 对象,数据将被读取到其中。streambuf 的所有权由调用者保留,调用者必须确保在调用完成处理程序之前 streambuf 保持有效。

delim

定界符字符。

标记

用于生成完成处理程序的 完成令牌,该处理程序将在读取完成时被调用。可能的完成令牌包括 use_futureuse_awaitableyield_context,或具有正确完成签名的函数对象。完成处理程序的函数签名必须是:

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

  // The number of bytes in the streambuf's get
  // area up to and including the delimiter.
  // 0 if an error occurred.
  std::size_t bytes_transferred
);

无论异步操作是否立即完成,都不会在此函数内部调用完成处理程序。对于立即完成的情况,处理程序的调用将以等同于使用 async_immediate 的方式进行。

完成签名
void(boost::system::error_code, std::size_t)
备注

在成功的 async_read_until 操作后,streambuf 中可能包含定界符之外的额外数据。应用程序通常会将这些数据保留在 streambuf 中,供后续的 async_read_until 操作检查。

示例

异步读取数据到 streambuf,直到遇到换行符。

boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
  if (!e)
  {
    std::istream is(&b);
    std::string line;
    std::getline(is, line);
    ...
  }
}
...
boost::asio::async_read_until(s, b, '\n', handler);

async_read_until 操作成功完成后,缓冲区 b 包含定界符。

{ 'a', 'b', ..., 'c', '\n', 'd', 'e', ... }

然后,对 std::getline 的调用提取直到包括换行符(该换行符将被丢弃)的数据,因此字符串 line 包含:

{ 'a', 'b', ..., 'c' }

剩余数据如下留在缓冲区 b 中:

{ 'd', 'e', ... }

这些数据可能是新行的开头,供后续的 async_read_until 操作提取。

按操作取消

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

  • cancellation_type::terminal
  • cancellation_type::partial

如果 AsyncReadStream 类型的 async_read_some 操作也支持这些值。


PrevUpHomeNext