Boost C++ 库

……是世界上备受推崇且设计精良的 C++ 库项目之一。 Herb SutterAndrei Alexandrescu, C++ Coding Standards

async_read(8 个重载中的第 6 个) - Boost C++ 函数库
PrevUpHomeNext

启动一个异步操作,从流中读取一定量的数据。

template<
    typename AsyncReadStream,
    typename Allocator,
    typename CompletionCondition,
    typename ReadToken = default_completion_token_t<        typename AsyncReadStream::executor_type>>
DEDUCED async_read(
    AsyncReadStream & s,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    ReadToken && token = default_completion_token_t< typename AsyncReadStream::executor_type >(),
    constraint_t< is_completion_condition< CompletionCondition >::value >  = 0);

此函数用于从流中异步读取指定数量的字节数据。它是 异步操作 的发起函数,并且始终立即返回。异步操作将一直进行,直到以下任一条件成立:

  • 提供的缓冲区已满(即已达到最大大小)。
  • completion_condition 函数对象返回 0。

此操作是通过零次或多次调用流的 async_read_some 函数来实现的,称为组合操作。程序必须确保在操作完成之前,流不再执行其他读取操作(例如 async_read、流的 async_read_some 函数或执行读取的任何其他组合操作)。

参数

s

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

b

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

completion_condition

用于确定读取操作是否完成的函数对象。函数对象的签名必须是:

std::size_t completion_condition(
  // Result of latest async_read_some operation.
  const boost::system::error_code& error,

  // Number of bytes transferred so far.
  std::size_t bytes_transferred
);

返回值为 0 表示读取操作已完成。非零返回值表示在下次调用流的 async_read_some 函数时要读取的最大字节数。

标记

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

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

  // Number of bytes copied into the buffers. If an error
  // occurred, this will be the number of bytes successfully
  // transferred prior to the error.
  std::size_t bytes_transferred
);

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

完成签名
void(boost::system::error_code, std::size_t)
按操作取消

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

  • cancellation_type::terminal
  • cancellation_type::partial

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


PrevUpHomeNext