bytemuck/
no_uninit.rs

1use crate::Pod;
2use core::num::{
3  NonZeroI128, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI8, NonZeroIsize,
4  NonZeroU128, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize,
5};
6
7/// Marker trait for "plain old data" types with no uninit (or padding) bytes.
8///
9/// The requirements for this is very similar to [`Pod`],
10/// except that it doesn't require that all bit patterns of the type are valid,
11/// i.e. it does not require the type to be [`Zeroable`][crate::Zeroable].
12/// This limits what you can do with a type of this kind, but also broadens the
13/// included types to things like C-style enums. Notably, you can only cast from
14/// *immutable* references to a [`NoUninit`] type into *immutable* references of
15/// any other type, no casting of mutable references or mutable references to
16/// slices etc.
17///
18/// [`Pod`] is a subset of [`NoUninit`], meaning that any `T: Pod` is also
19/// [`NoUninit`] but any `T: NoUninit` is not necessarily [`Pod`]. If possible,
20/// prefer implementing [`Pod`] directly. To get more [`Pod`]-like functionality
21/// for a type that is only [`NoUninit`], consider also implementing
22/// [`CheckedBitPattern`][crate::CheckedBitPattern].
23///
24/// The rules for padding for various types and representations are documented
25/// in the Rust reference section on [type layout].
26///
27/// # Derive
28///
29/// A `#[derive(NoUninit)]` macro is provided under the `derive` feature flag
30/// which will automatically validate the requirements of this trait and
31/// implement the trait for you for both enums and structs. This is the
32/// recommended method for implementing the trait, however it's also possible to
33/// do manually. If you implement it manually, you *must* carefully follow the
34/// below safety rules.
35///
36/// # Safety
37///
38/// The same as [`Pod`] except we disregard the rule about it must
39/// allow any bit pattern (i.e. it does not need to be
40/// [`Zeroable`][crate::Zeroable]). Still, this is a quite strong guarantee
41/// about a type, so *be careful* whem implementing it manually.
42///
43/// * The type must be inhabited (eg: no
44///   [Infallible](core::convert::Infallible)).
45/// * The type must not contain any uninit (or padding) bytes, either in the
46///   middle or on the end (eg: no `#[repr(C)] struct Foo(u8, u16)`, which has
47///   padding in the middle, and also no `#[repr(C)] struct Foo(u16, u8)`, which
48///   has padding on the end).
49/// * Structs need to have all fields also be `NoUninit`.
50/// * Structs need to be `repr(C)` or `repr(transparent)`. In the case of
51///   `repr(C)`, the `packed` and `align` repr modifiers can be used as long as
52///   all other rules end up being followed.
53/// * Enums need to be `#[repr(Int)]`, `#[repr(C)]`, or both.
54/// * Enums may have fields. If the enum has fields,
55///     * Each variant's fields must individually follow the same rules as a struct
56///     * All variants must be the same size, and require no padding-to-alignment
57///     * There must be no padding needed between the discriminant type and the
58///       "fields struct" of any variant
59/// * It is disallowed for types to contain pointer types, `Cell`, `UnsafeCell`,
60///   atomics, and any other forms of interior mutability.
61/// * More precisely: A shared reference to the type must allow reads, and
62///   *only* reads. RustBelt's separation logic is based on the notion that a
63///   type is allowed to define a sharing predicate, its own invariant that must
64///   hold for shared references, and this predicate is the reasoning that allow
65///   it to deal with atomic and cells etc. We require the sharing predicate to
66///   be trivial and permit only read-only access.
67/// * There's probably more, don't mess it up (I mean it).
68///
69/// [type layout]: <https://doc.rust-lang.org/reference/type-layout.html>
70pub unsafe trait NoUninit: Sized + Copy + 'static {}
71
72unsafe impl<T: Pod> NoUninit for T {}
73
74unsafe impl NoUninit for char {}
75
76unsafe impl NoUninit for bool {}
77
78unsafe impl NoUninit for NonZeroU8 {}
79unsafe impl NoUninit for NonZeroI8 {}
80unsafe impl NoUninit for NonZeroU16 {}
81unsafe impl NoUninit for NonZeroI16 {}
82unsafe impl NoUninit for NonZeroU32 {}
83unsafe impl NoUninit for NonZeroI32 {}
84unsafe impl NoUninit for NonZeroU64 {}
85unsafe impl NoUninit for NonZeroI64 {}
86unsafe impl NoUninit for NonZeroU128 {}
87unsafe impl NoUninit for NonZeroI128 {}
88unsafe impl NoUninit for NonZeroUsize {}
89unsafe impl NoUninit for NonZeroIsize {}
bytemuck/no_uninit.rs

bytemuck/
no_uninit.rs
