Boost C++ 库

……世界上最受推崇、设计最精良的 C++ 库项目之一。 Herb SutterAndrei AlexandrescuC++ Coding Standards

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

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

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename ReadToken = default_completion_token_t<        typename AsyncReadStream::executor_type>>
DEDUCED async_read(
    AsyncReadStream & s,
    const MutableBufferSequence & buffers,
    ReadToken && token = default_completion_token_t< typename AsyncReadStream::executor_type >(),
    constraint_t< is_mutable_buffer_sequence< MutableBufferSequence >::value >  = 0,
    constraint_t< !is_completion_condition< ReadToken >::value >  = 0);

此函数用于从流中异步读取指定字节数的数据。它是一个异步操作的启动函数,并且总是立即返回。异步操作将继续执行,直到满足以下条件之一:

  • 提供的缓冲区已满。即,传输的字节数等于缓冲区大小的总和。
  • 发生错误。

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

参数

s

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

缓冲区

一个或多个缓冲区,用于读取数据。缓冲区大小的总和指示了从流中读取的最大字节数。虽然缓冲区对象可以根据需要复制,但底层内存块的所有权由调用者保留,调用者必须确保在调用完成处理程序之前它们保持有效。

标记

用于生成完成处理程序的完成标记,将在读取完成时调用。可能的完成标记包括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)
示例

要将数据读取到单个缓冲区中,请使用 buffer 函数,如下所示:

boost::asio::async_read(s, boost::asio::buffer(data, size), handler);

有关一次性读取到多个缓冲区的信息,以及如何将其与数组、boost::array或std::vector配合使用,请参阅buffer文档。

备注

此重载等同于调用

boost::asio::async_read(
   s, buffers,
   boost::asio::transfer_all(),
   handler);
按操作取消

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

  • cancellation_type::terminal
  • cancellation_type::partial

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


PrevUpHomeNext