Crate const_type_layout

const-type-layout is a type layout comparison aid, providing a #[derive]able TypeLayout trait that provides a const TypeLayoutInfo struct containing:

• The type’s name, size, and minimum alignment
• The type’s structure, i.e. struct vs. union vs. enum
• Each field’s name and offset
• Each variant’s name and discriminant
• Whether each variant / field is inhabited or uninhabited

The auto-implemented TypeGraphLayout trait also provides a const TypeLayoutGraph struct that describes the deep type layout, including the layouts of all the types mentioned by this type, e.g. in its fields.

This crate heavily builds on the original runtime type-layout crate by Lucien Greathouse.

Examples

The layout of types is only defined if they’re #[repr(C)]. This crate works on non-#[repr(C)] types, but their layout is unpredictable.

use const_type_layout::TypeLayout;

#[derive(TypeLayout)]
#[repr(C)]
struct Foo {
    a: u8,
    b: u32,
}

assert_eq!(
    format!("{:#?}", Foo::TYPE_LAYOUT),
r#"TypeLayoutInfo {
    name: "rust_out::main::_doctest_main_src_lib_rs_45_0::Foo",
    size: 8,
    alignment: 4,
    structure: Struct {
        repr: "C",
        fields: [
            Field {
                name: "a",
                offset: Inhabited(
                    0,
                ),
                ty: "u8",
            },
            Field {
                name: "b",
                offset: Inhabited(
                    4,
                ),
                ty: "u32",
            },
        ],
    },
}"#
)

Over-aligned types have trailing padding, which can be a source of bugs in some FFI scenarios:

use const_type_layout::TypeLayout;

#[derive(TypeLayout)]
#[repr(C, align(128))]
struct OverAligned {
    value: u8,
}

assert_eq!(
    format!("{:#?}", OverAligned::TYPE_LAYOUT),
r#"TypeLayoutInfo {
    name: "rust_out::main::_doctest_main_src_lib_rs_88_0::OverAligned",
    size: 128,
    alignment: 128,
    structure: Struct {
        repr: "C,align(128)",
        fields: [
            Field {
                name: "value",
                offset: Inhabited(
                    0,
                ),
                ty: "u8",
            },
        ],
    },
}"#
)

Modules

• inhabited
  Helper module to compute whether a combination of types implementing crate::TypeLayout are inhabited or uninhabited.
• typeset
  Helper module to compute the set of types that a type links to and expand it into the complete type graph.

Macros

• discriminant
  Helper macro to construct a Discriminant from its constant value.

Structs

• Discriminant
  Discriminant of an enum variant.
• Field
  Descriptor of the shallow layout of a field.
• TypeLayoutGraph
  Description of the deep layout of a type.
• TypeLayoutInfo
  Description of the shallow layout of a type.
• Variant
  Description of the shallow layout of a variant

Enums

• MaybeUninhabited
  Optional value that exists if some other type is inhabited.
• TypeStructure
  Description of the shallow structure of a type.

Traits

• TypeGraphLayout
  Utility trait that provides the deep layout of a type.
• TypeLayout
  Utility trait that provides the shallow layout of a type.

Functions

• hash_type_graph
  Hash this type’s TypeLayoutGraph using the provided seed.
• serialise_type_graph
  Serialise this type’s TypeLayoutGraph into an array of bytes of length serialised_type_graph_len.
• serialised_type_graph_len
  Compute the number of bytes that this type’s TypeLayoutGraph serialises into.

Derive Macros

• TypeLayoutderive
  Provides the #[derive(TypeLayout)] implementation for the const_type_layout::TypeLayout trait.