boost::corosio::io_stream::read_some

Asynchronously read data from the stream.

Synopsis

Declared in <boost/corosio/io_stream.hpp>

template<capy::MutableBufferSequence MB>
auto
read_some(MB const& buffers);

Description

This operation suspends the calling coroutine and initiates a kernel‐level read. The coroutine resumes when the operation completes.

  • The operation completes when:

  • At least one byte has been read into the buffer sequence

  • The peer closes the connection (EOF)

  • An error occurs

  • The operation is cancelled via stop token or `cancel()`

Concurrency

At most one write operation may be in flight concurrently with this read. No other read operations may be in flight until this operation completes. Note that concurrent in‐flight operations does not imply the initiating calls may be made concurrently; all calls must be serialized.

Cancellation

Supports cancellation via std::stop_token propagated through the IoAwaitable protocol, or via the I/O object's cancel() member. When cancelled, the operation completes with an error that compares equal to capy::cond::canceled.

Preconditions

The stream must be open and connected.

  • `capy::cond::eof` ‐ Peer closed connection (TCP FIN)

  • `capy::cond::canceled` ‐ Operation was cancelled

Example

// Simple read with error handling
auto [ec, n] = co_await stream.read_some( capy::buffer( buf ) );
if( ec == capy::cond::eof )
    co_return;  // Connection closed gracefully
if( ec.failed() )
    capy::detail::throw_system_error( ec );
process( buf, n );

This operation may read fewer bytes than the buffer capacity. Use a loop or capy::async_read to read an exact amount.

Return Value

An awaitable yielding (error_code, std::size_t). On success, bytes_transferred contains the number of bytes read. Compare error codes to conditions, not specific values:

Parameters

Name Description

buffers

The buffer sequence to read data into. The caller retains ownership and must ensure validity until the operation completes.

See Also

write_some, capy::async_read

Created with MrDocs