boost::capy::read

Asynchronously read until the buffer sequence is full.

Synopsis

Declared in <boost/capy/read.hpp>

io_task<std::size_t>
read(
    auto& stream,
    auto const& buffers);

Description

Reads data from the stream by calling read_some repeatedly until the entire buffer sequence is filled or an error occurs.

  • The operation completes when:

  • The buffer sequence is completely filled

  • An error occurs (including `cond::eof`)

  • The operation is cancelled

Cancellation

Supports cancellation via stop_token propagated through the IoAwaitable protocol. When cancelled, returns with cond::canceled.

  • `cond::eof` ‐ Stream reached end before buffer was filled

  • `cond::canceled` ‐ Operation was cancelled

Example

task<> read_message( ReadStream auto& stream )
{
    char header[16];
    auto [ec, n] = co_await read( stream, mutable_buffer( header ) );
    if( ec == cond::eof )
        co_return;  // Connection closed
    if( ec )
        detail::throw_system_error( ec );
    // header contains exactly 16 bytes
}

Return Value

An awaitable yielding (error_code, std::size_t). On success, n equals buffer_size(buffers). On error, n is the number of 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 buffer sequence to fill. The caller retains ownership and must ensure validity until the operation completes.

See Also

read_some, ReadStream, MutableBufferSequence

Created with MrDocs