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.