boost::capy::read
Asynchronously read all data from a stream into a dynamic buffer.
Synopsis
Declared in <boost/capy/read.hpp>
io_task<std::size_t>
read(
auto& stream,
auto&& buffers,
std::size_t initial_amount = 2048);Description
Reads data by calling read_some repeatedly until EOF is reached or an error occurs. Data is appended using prepare/commit semantics. The buffer grows with 1.5x factor when filled.
-
The operation completes when:
-
End‐of‐stream is reached (`cond::eof`)
-
An error occurs
-
The operation is cancelled
Cancellation
Supports cancellation via stop_token propagated through the IoAwaitable protocol. When cancelled, returns with cond::canceled.
-
`cond::canceled` ‐ Operation was cancelled
Example
task<std::string> read_body( ReadStream auto& stream )
{
std::string body;
auto [ec, n] = co_await read( stream, string_dynamic_buffer( &body ) );
if( ec )
detail::throw_system_error( ec );
return body;
}Asynchronously read all data from a source into a dynamic buffer.
Reads data by calling source.read repeatedly until EOF is reached or an error occurs. Data is appended using prepare/commit semantics. The buffer grows with 1.5x factor when filled.
-
The operation completes when:
-
End‐of‐stream is reached (`cond::eof`)
-
An error occurs
-
The operation is cancelled
Cancellation
Supports cancellation via stop_token propagated through the IoAwaitable protocol. When cancelled, returns with cond::canceled.
-
`cond::canceled` ‐ Operation was cancelled
Example
task<std::string> read_body( ReadSource auto& source )
{
std::string body;
auto [ec, n] = co_await read( source, string_dynamic_buffer( &body ) );
if( ec )
detail::throw_system_error( ec );
return body;
}Return Value
An awaitable yielding (error_code, std::size_t). On success (EOF), ec is clear and n is total bytes read. On error, n is bytes read before the error. Compare error codes to conditions:
Parameters
| Name | Description |
|---|---|
stream |
The stream to read from. The caller retains ownership. |
buffers |
The dynamic buffer to append data to. Must remain valid until the operation completes. |
initial_amount |
Initial bytes to prepare (default 2048). |
source |
The source to read from. The caller retains ownership. |