#[derive(FromBytes)]
Expand description
Analyzes whether a type is FromBytes
.
This derive analyzes, at compile time, whether the annotated type satisfies
the safety conditions of FromBytes
and implements FromBytes
if it is
sound to do so. This derive can be applied to structs, enums, and unions;
e.g.:
#[derive(FromZeroes, FromBytes)]
struct MyStruct {
...
}
#[derive(FromZeroes, FromBytes)]
#[repr(u8)]
enum MyEnum {
...
}
#[derive(FromZeroes, FromBytes)]
union MyUnion {
...
}
§Analysis
This section describes, roughly, the analysis performed by this derive to
determine whether it is sound to implement FromBytes
for a given type.
Unless you are modifying the implementation of this derive, or attempting to
manually implement FromBytes
for a type yourself, you don’t need to read
this section.
If a type has the following properties, then this derive can implement
FromBytes
for that type:
- If the type is a struct, all of its fields must be
FromBytes
. - If the type is an enum:
- It must be a C-like enum (meaning that all variants have no fields).
- It must have a defined representation (
repr
sC
,u8
,u16
,u32
,u64
,usize
,i8
,i16
,i32
,i64
, orisize
). - The maximum number of discriminants must be used (so that every possible
bit pattern is a valid one). Be very careful when using the
C
,usize
, orisize
representations, as their size is platform-dependent.
- The type must not contain any
UnsafeCell
s (this is required in order for it to be sound to construct a&[u8]
and a&T
to the same region of memory). The type may contain references or pointers toUnsafeCell
s so long as those values can themselves be initialized from zeroes (FromBytes
is not currently implemented for, e.g.,Option<*const UnsafeCell<_>>
, but it could be one day).
This analysis is subject to change. Unsafe code may only rely on the
documented safety conditions of FromBytes
, and must not rely on the
implementation details of this derive.
§Why isn’t an explicit representation required for structs?
Neither this derive, nor the safety conditions of FromBytes
, requires
that structs are marked with #[repr(C)]
.
Per the Rust reference,
The representation of a type can change the padding between fields, but does not change the layout of the fields themselves.
Since the layout of structs only consists of padding bytes and field bytes,
a struct is soundly FromBytes
if:
- its padding is soundly
FromBytes
, and - its fields are soundly
FromBytes
.
The answer to the first question is always yes: padding bytes do not have any validity constraints. A discussion of this question in the Unsafe Code Guidelines Working Group concluded that it would be virtually unimaginable for future versions of rustc to add validity constraints to padding bytes.
Whether a struct is soundly FromBytes
therefore solely depends on whether
its fields are FromBytes
.