Module io 

Async I/O traits, adapters, and capability infrastructure.

This module provides minimal AsyncRead and AsyncWrite traits, a safe ReadBuf type, and common adapters and extension futures. The design mirrors std::io and futures::io but is intentionally small and cancel-aware.

I/O Capability Model

Asupersync uses explicit capability-based I/O access. The IoCap trait defines the I/O capability boundary - tasks can only perform I/O when they have access to an implementation:

• Production: Real I/O via reactor (epoll/kqueue/IOCP)
• Lab: Virtual I/O for deterministic testing (see LabIoCap)

Cancel Safety

Read operations

• poll_read is cancel-safe (partial data is discarded by the caller).
• read_exact is not cancel-safe (partial state is retained).
• read_to_end is cancel-safe (collected bytes remain in the buffer).
• read_to_string is not fully cancel-safe (bytes are preserved, but a partial UTF-8 sequence at the end may be lost if cancelled).

Write operations

• poll_write is cancel-safe (partial writes are OK).
• write_all is not cancel-safe (partial writes may occur).
• WritePermit is cancel-safe (uncommitted data is discarded on drop).
• flush and shutdown are cancel-safe (can retry).

Copy operations

• copy is cancel-safe (bytes already written remain committed).
• copy_buf is cancel-safe (bytes already written remain committed).
• copy_with_progress is cancel-safe (progress callback is accurate).
• copy_bidirectional is cancel-safe (both directions can be partially complete).

Re-exports

pub use ext::AsyncReadExt;

pub use ext::AsyncReadVectoredExt;

pub use ext::ReadExact;

pub use ext::ReadToEnd;

pub use ext::ReadToString;

pub use ext::ReadU8;

pub use ext::ReadVectored;

pub use ext::AsyncWriteExt;

pub use ext::Buf;

pub use ext::Flush;

pub use ext::Shutdown;

pub use ext::WriteAll;

pub use ext::WriteAllBuf;

pub use ext::WriteU8;

pub use ext::WriteVectored;

pub use cap::IoCap;

pub use cap::IoNotAvailable;

pub use cap::LabIoCap;

Modules

cap

I/O capability trait for explicit capability-based I/O access.

ext

Extension traits and future adapters for async I/O.

Structs

BufReader

Async buffered reader.

BufWriter

Async buffered writer.

Chain

Chain two readers.

Copy

Future for the copy function.

CopyBidirectional

Future for the copy_bidirectional function.

CopyBuf

Future for the copy_buf function.

CopyWithProgress

Future for the copy_with_progress function.

Lines

Iterator over the lines of an AsyncBufRead.

ReadBuf

Buffer for reading data.

ReadHalf

The read half of a split stream.

SplitStream

A wrapper around a stream that allows splitting into read/write halves.

Take

Take at most limit bytes from a reader.

WriteHalf

The write half of a split stream.

WritePermit

A permit for cancel-safe writes.

Enums

SeekFrom

Enumeration of possible methods to seek within an I/O object.

Traits

AsyncBufRead

Buffered read trait for efficient copy operations.

AsyncRead

Async non-blocking read.

AsyncReadVectored

Async non-blocking read into multiple buffers (vectored I/O).

AsyncSeek

Trait for async seeking.

AsyncWrite

Async non-blocking write.

AsyncWriteVectored

Async non-blocking write from multiple buffers (vectored I/O).

Functions

copy

Copy all data from a reader to a writer.

copy_bidirectional

Bidirectional copy between two streams.

copy_buf

Copy all data from a buffered reader to a writer.

copy_with_progress

Copy all data from a reader to a writer with progress reporting.

split

Convenience function to split a stream into read and write halves.