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.