Crate abio

source ·
Expand description

abio

abio is a low-level crate for performing endian-aware operations on raw byte slices, converting to and from concrete types using zero-copy serialization and deserialization routines.

You can find more information about this crate’s API within the official crate documentation.

Design / Purpose

This crate is an attempt at implementing “safe transmute”.

Sans-I/O Operations

This crate provides its own custom [ABI][ABI] by enforcing a set of contracts via traits. operates directly on binary data, or bytes. There is no actual I/O performed at any point within the codebase. This design approach is heavily inspired by is that it allows decoupling of the reading and writing logic from the I/O itself. To be more specific, this crate is agnostic with regard to where the bytes originate from.

Predictable Type Layout

When you use the standard Rust ABI without specifying a #[repr(..)] attribute, the Rust compiler has the freedom to lay out your data structures in memory however it deems optimal. This can mean that the layout might change between different compiler versions, optimization levels, or even different compilation targets. As a result, the standard Rust ABI does not provide any guarantees about the memory layout of your types.

This does not necessarily mean that the layout will change or be non-deterministic, but rather that it’s not something you should rely on if you need to have a stable memory layout.

If you need to read and write raw bytes from/to your data structures, and you need this to work reliably and soundly, then you should use one of the #[repr(..)] attributes to specify the layout of your data structures. For example, #[repr(C)] is commonly used for this purpose, because it specifies that your data structure should have the same memory layout as it would in C, which is a stable, well-defined layout.

Soundness

Creating code that isn’t grounded on an [ABI (Application Binary Interface)][ABI] with a predictable layout can easily introduce unsoundness. This crate, however, prioritizes safety over performance when faced with a trade-off, as high performance is rendered insignificant in the absence of sound and safe code. Therefore, it aims to strike an optimal balance between these two factors, which is arguably the most pragmatic approach.

Re-exports

  • pub use source::ByteArray;

Modules

  • decode
    Module related to how data is interpreted, such as its layout and endianness.
  • endian
    Module for working with endian-aware byte sequences.
  • integer
    Wrapper types and extensions for Rust’s built-in integer primitives.

Structs

  • BigEndian
    Big endian byte order serialization.
  • Chunk
    A fixed-size array of bytes, or “chunk”.
  • Codec
    Configurable type that is used to decode and encode data.
  • CodecBuilder
    Builder that allows constructing validated instances of the Codec type.
  • Error
    Core error type for the [abio][abio] crate.
  • Limit
    Maximum number of bytes a configured Codec instance can handle at a time.
  • LittleEndian
    Little endian byte order serialization.
  • Slice
    Contiguous region of memory containing a borrowed sequence of bytes.
  • Span
    A region of memory defined by a pair of indices marking the start and end offsets of an allocated object in memory.

Enums

  • Endian
    Byte order serialization variant.

Traits

  • Abi
    A trait that a type must implement to be considered compatible with the ABI.
  • Array
    A fixed, statically sized chunk of data that can be read from the Source.
  • Buf
    Trait to define types that may be represented as a borrowed slice of bytes.
  • BytesOf
    Trait to define types that can be represented as raw bytes.
  • Decode
    The Decode trait defines how a type is deserialized or decoded from a slice or chunk of bytes. It provides a way to translate raw byte sequences back into meaningful data in a structured manner.
  • Endianness
    An internal trait that encompasses common trait bounds for the [ByteOrder] trait. This trait implements [Sealed], preventing downstream crates from implementing this trait.
  • Source
    Types that represent valid memory for use as an input Source into the abstract machine defined by this crate’s ABI, or Application Binary Interface.
  • Zeroable
    Trait defining Types that can exist represented by the all-zero byte-pattern.

Type Definitions

Derive Macros