2 releases
0.0.2 | Apr 10, 2023 |
---|---|
0.0.1 | Apr 10, 2023 |
#275 in FFI
31KB
576 lines
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
][try_from] and [iffi::into
][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
.
Dependencies
~0.4–1MB
~20K SLoC