Crate iffi

source ·
Expand description

Safe conversion between FFI-safe and ergonomic Rust types.

An implementation of Iffi trait (which can be derived) on a type T over a universe U (the type parameter on the trait) provides assertions that a value of type U can be safely transmuted into a value of type T.

iffi::try_from and iffi::into perform the conversion safely.

Glossary & Concepts

FFI-safe

a type that can be used with FFI.

This can be a primitve, a type marked with #[repr(C)] or #[repr(Int)], or a type marked with #[repr(transparent)] with only one non-zero sized field which must be FFI-safe.

bit-pattern

a sequence of bits representing a potential value of a type.

Each type defines some bit-patterns (with the same number of bits as the type) that are valid and others that are invalid.

For example, for u16, all bit-patterns are valid because 0x0000 through 0xffff are all correctly initialized u16 values, but for bool only the patterns 0x00 and 0x01, (false and true respectively) are valid. 0x02..=0xff are all invalid bit-patterns for bool.

An invalid bit-pattern is also called a niche. Types like u16 where all bit-patterns are valid are nicheless.

This definition is subtly different to the one in the Unsafe Code Guidelines. In the context of bit-patterns this crate assumes all bits are initialized, so there is a one-to-one relationship between invalid bit patterns and niches.

well-defined

a potential value represented in memory by a valid bit-pattern.

A null reference or zeroed NonZero* is not well-defined, for example.

nicheless

a type with no niches i.e. no invalid bit-patterns.

The Nicheless trait cannot be automatically implemented and must be derived or implemented manually.

ZSTs are always nicheless. Uninhabited types are never nicheless.

A more technical definition is availible in the Unsafe Code Guidelines.

layout

the combination of the size, alignment and ABI behaviour of a type.

universe

a nicheless type with the same layout as some potentially non-nicheless type.

MaybeInvalid<T> is a universe of all T.

A type may have many universes. As an example, NonZeroU8 has the universes MaybeInvalid<NonZeroU8> and u8.

Structs

  • BitPattern
    A dynamically-sized pattern of bits.
  • BitRanges
    A set of ranges of bit-patterns that are applicable for a type.
  • Error
    An error encountered while converting with Iffi, wrapped with type name information.
  • MaybeInvalid
    Represents a value of the type T that may not be well-defined.

Enums

Traits

  • Iffi
    The core trait of the iffi crate.
  • Nicheless
    Indicates that a value of this type is FFI-safe and well-defined no matter the underlying bit-pattern.
  • OneNiche
    Indicates that the type has exactly one niche, which is filled by niche optimization and so implements Nicheless in option-like enums (Option<T>, Result<T, ()>).

Functions

Derive Macros