启动一个异步操作,从流中读取一定量的数据。
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);
此函数用于从流中异步读取一定数量的字节数据。它是 异步操作 的发起函数,并且总是立即返回。异步操作将继续进行,直到满足以下条件之一:
此操作是通过零次或多次调用流的 async_read_some 函数来实现的,并被称为 组合操作。程序必须确保在操作完成之前,流不执行任何其他读取操作(例如 async_read、流的 async_read_some 函数,或任何执行读取的其他组合操作)。
要从中读取数据的流。该类型必须支持 AsyncReadStream 概念。
一个 basic_streambuf 对象,数据将被读取到其中。streambuf 的所有权由调用者保留,调用者必须保证在调用完成处理程序之前它保持有效。
用于确定读取操作是否完成的函数对象。函数对象的签名必须是:
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_future、use_awaitable、yield_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 操作也支持这些值。