Crate io

Traits and types for expressing I/O transfers of both byte-wise and block-wise granularity.

The important items are summarized below:

• BlockReader, BlockWriter: traits that represent I/O streams which can be read from or written to at the granularity of a single block (as the smallest transferable chunk).
• BlockIo: a parent trait that specifies the size in bytes of each block in a block-based I/O stream.
• KnownLength: a trait that represents an I/O stream with a known length, such as a disk drive.
• ByteReader, ByteWriter: traits that represent I/O streams which can be read from or written to at the granularity of an individual byte.
• Wrapper types that allow byte-wise access atop block-based I/O streams: ByteReaderWrapper, ByteWriterWrapper, ByteReaderWriterWrapper.
  • Notably, the blocks_from_bytes() function is useful for calculating the set of block-based I/O transfers that are needed to satisfy an arbitrary byte-wise transfer.

For example, a storage device like a hard drive that supports transfers of 512-byte blocks should implement BlockIo, BlockReader, BlockWriter, and KnownLength traits. A user can then use those traits directly to transfer whole blocks to/from the device, or wrap the storage device in one of the byte-wise reader/writer types in order to transfer arbitrary bytes (as little as one byte) at a time to/from the device.

We also provide the LockableIo type for convenient use with I/O streams or devices that exist behind a shared lock, e.g., Arc<Mutex<IO>>, Mutex<IO>, etc. This allows you to access the I/O stream transparently through the lock by using traits that the interior IO object implements, such as the block-wise I/O traits listed above.

Stateless vs. Stateful I/O

Note that the above traits represent “stateless” access into I/O streams or devices, in that successive read/write operations will not advance any kind of “offset” or cursor.

To read or write while tracking the current offset into the I/O stream, we provide the ReaderWriter, Reader, and Writer structs, which act as “stateful” wrappers around an underlying “stateless” I/O stream (such as a stateless ByteReader or ByteWriter). This offers a more convenient interface with more traditional I/O behavior, in which the next read or write operation will start where the prior one ended.

Structs

BlockByteTransfer

Describes an operation for performing byte-wise I/O on a block-based I/O stream.

ByteReaderWrapper

A wrapper struct that implements a byte-wise reader atop a block-based reader.

ByteReaderWriterWrapper

A wrapper struct that implements a byte-wise reader and writer atop a block-based reader and writer.

ByteWriterWrapper

A wrapper struct that implements a byte-wise writer atop a block-based reader and writer.

LockableIo

A struct that holds an IO object wrapped in a Lockable type L, for the purpose of forwarding various IO-related traits through the lock to the IO type.

Reader

A stateful reader that keeps track of its current offset within the internal stateless ByteReader I/O stream.

ReaderWriter

A readable and writable “stateful” I/O stream that keeps track of its current offset within its internal stateless I/O stream.

Writer

A stateful writer that keeps track of its current offset within the internal stateless ByteWriter I/O stream.

Enums

IoError

Errors that can be returned from I/O operations.

Traits

BlockIo

A parent trait used to specify the block size (in bytes) of I/O transfers (read and write operations). See its use in BlockReader and BlockWriter.

BlockReader

A trait that represents an I/O stream (e.g., an I/O device) that can be read from in blocks. The block size specifies the minimum granularity of each transfer, as given by the BlockIo::block_size() function.

BlockWriter

A trait that represents an I/O stream (e.g., an I/O device) that can be written to in blocks. The block size specifies the minimum granularity of each transfer, as given by the BlockIo::block_size() function.

ByteReader

A trait that represents an I/O stream that can be read from at the granularity of individual bytes, but which does not track the current offset into the stream.

ByteWriter

A trait that represents an I/O stream that can be written to, but which does not track the current offset into the stream.

KnownLength

A trait that represents an I/O stream that has a known length, e.g., a disk drive.

Functions

blocks_from_bytes

Calculates block-wise bounds for an I/O transfer based on a byte-wise range into a block-wise stream.