Crate iroh_io

Traits for async local IO, and implementations for local files, http resources and memory. This crate provides two core traits: AsyncSliceReader and AsyncSliceWriter.

Memory implementations for Bytes and BytesMut are provided by default, file and http are behind features.

Futures for the two core traits are not required to be Send.

This allows implementing these traits for types that are not thread safe, such as many embedded databases.

It also allows for omitting thread synchronization primitives. E.g. you could use an Rc<RefCell<BytesMut>> instead of a much more costly Arc<Mutex<BytesMut>>.

The downside is that you have to use a local executor, e.g. LocalPoolHandle, if you want to do async IO in a background task.

A good blog post providing a rationale for these decisions is Local Async Executors and Why They Should be the Default.

All futures returned by this trait must be polled to completion, otherwise all subsequent calls will produce an io error.

So it is fine to e.g. limit a call to read_at with a timeout, but once a future is dropped without being polled to completion, the reader is not useable anymore.

All methods, even those that do not modify the underlying resource, take a mutable reference to self. This is to enforce linear access to the underlying resource.

In general it is assumed that readers are cheap, so in case of an error you can always get a new reader. Also, if you need concurrent access to the same resource, create multiple readers.

One thing you might wonder is why there are separate methods for writing Bytes and writing slices. The reason is that if you already have Bytes and the underlying writer needs Bytes, you can avoid an allocation.

Modules

file

Support for the File

http_adapter

Support for the HttpAdapter

stats

Utilities for measuring time for io ops.

Structs

ConcatenateSliceWriter

Utility to convert an AsyncWrite into an AsyncSliceWriter by just ignoring the offsets

File

A wrapper around a std::fs::File that implements AsyncSliceReader and AsyncSliceWriter

HttpAdapter

A struct that implements AsyncSliceReader using HTTP range requests

TokioStreamReader

Utility to convert a tokio::io::AsyncRead into an AsyncStreamReader.

TokioStreamWriter

Utility to convert a tokio::io::AsyncWrite into an AsyncStreamWriter.

Traits

AsyncSliceReader

A trait to abstract async reading from different resource.

AsyncSliceReaderExt

Extension trait for AsyncSliceReader.

AsyncSliceWriter

A trait to abstract async writing to different resources.

AsyncStreamReader

A non seekable reader, e.g. a network socket.

AsyncStreamWriter

A non seekable writer, e.g. a network socket.