boost::corosio::io_stream

Platform stream with read/write operations.

Synopsis

Declared in <boost/corosio/io_stream.hpp>

class io_stream
    : public io_object

Description

This base class provides the fundamental async read and write operations for kernel‐level stream I/O. Derived classes wrap OS‐specific stream implementations (sockets, pipes, etc.) and satisfy capy::ReadStream and capy::WriteStream concepts.

Semantics

Concrete classes wrap direct platform I/O completed by the kernel. Functions taking io_stream& signal "platform implementation required" ‐ use this when you need actual kernel I/O rather than a mock or test double.

For generic stream algorithms that work with test mocks, use template<capy::Stream S> instead of io_stream&.

Thread Safety

Distinct objects: Safe. Shared objects: Unsafe. All calls to a single stream must be made from the same implicit or explicit serialization context.

Example

// Read until buffer full or EOF
capy::task<> read_all( io_stream& stream, std::span<char> buf )
{
    std::size_t total = 0;
    while( total < buf.size() )
    {
        auto [ec, n] = co_await stream.read_some(
            capy::buffer( buf.data() + total, buf.size() - total ) );
        if( ec == capy::cond::eof )
            break;
        if( ec.failed() )
            capy::detail::throw_system_error( ec );
        total += n;
    }
}