Trait bytemuck::AnyBitPattern
source · pub unsafe trait AnyBitPattern: Zeroable + Sized + Copy + 'static { }Expand description
Marker trait for “plain old data” types that are valid for any bit pattern.
The requirements for this is very similar to Pod, except that the type
can allow uninit (or padding) bytes. This limits what you can do with a type
of this kind, but also broadens the included types to repr(C) structs
that contain padding as well as unions. Notably, you can only cast
immutable references and owned values into AnyBitPattern types, not
mutable references.
Pod is a subset of AnyBitPattern, meaning that any T: Pod is also
AnyBitPattern but any T: AnyBitPattern is not necessarily Pod.
AnyBitPattern is a subset of Zeroable, meaning that any T: AnyBitPattern is also Zeroable, but any T: Zeroable is not
necessarily AnyBitPattern
Derive
A #[derive(AnyBitPattern)] macro is provided under the derive feature
flag which will automatically validate the requirements of this trait and
implement the trait for you for both structs and enums. This is the
recommended method for implementing the trait, however it’s also possible to
do manually. If you implement it manually, you must carefully follow the
below safety rules.
- *NOTE: even
C-style, fieldless enums are intentionally excluded from this trait, since it is unsound for an enum to have a discriminant value that is not one of its defined variants.
Safety
Similar to Pod except we disregard the rule about it must not contain
uninit bytes. Still, this is a quite strong guarantee about a type, so be
careful when implementing it manually.
- The type must be inhabited (eg: no Infallible).
- The type must be valid for any bit pattern of its backing memory.
- Structs need to have all fields also be
AnyBitPattern. - It is disallowed for types to contain pointer types,
Cell,UnsafeCell, atomics, and any other forms of interior mutability. - More precisely: A shared reference to the type must allow reads, and only reads. RustBelt’s separation logic is based on the notion that a type is allowed to define a sharing predicate, its own invariant that must hold for shared references, and this predicate is the reasoning that allow it to deal with atomic and cells etc. We require the sharing predicate to be trivial and permit only read-only access.
- There’s probably more, don’t mess it up (I mean it).