musli_zerocopy/mem/
maybe_uninit.rs

1use core::fmt;
2use core::mem::{size_of, ManuallyDrop};
3use core::ptr::NonNull;
4use core::slice;
5
6use crate::buf;
7use crate::pointer::{Pointee, Size};
8use crate::traits::ZeroCopy;
9
10/// A value which might or might not have been initialized.
11///
12/// This differs from the standard library
13/// [`MaybeUninit`][core::mem::MaybeUninit] in that its methods does not inherit
14/// the alignment of the inner value so it can correctly refer to elements of
15/// `T` in unaligned memory. Which [`OwnedBuf`] might refer to.
16///
17/// # Examples
18///
19/// Writing to a pre-allocation location in an [`OwnedBuf`].
20///
21/// [`OwnedBuf`]: crate::buf::OwnedBuf
22///
23/// ```
24/// use musli_zerocopy::{OwnedBuf, Ref, ZeroCopy};
25/// use musli_zerocopy::mem::MaybeUninit;
26///
27/// #[derive(ZeroCopy)]
28/// #[repr(C)]
29/// struct Custom { string: Ref<str> }
30///
31/// let mut buf = OwnedBuf::new();
32///
33/// let reference: Ref<MaybeUninit<Custom>> = buf.store_uninit::<Custom>();
34///
35/// let string = buf.store_unsized("Hello World!");
36///
37/// buf.load_uninit_mut(reference).write(&Custom { string });
38///
39/// let reference = reference.assume_init();
40///
41/// assert_eq!(reference.offset(), 0);
42///
43/// let custom = buf.load(reference)?;
44/// assert_eq!(buf.load(custom.string)?, "Hello World!");
45/// # Ok::<_, musli_zerocopy::Error>(())
46/// ```
47#[repr(C, packed)]
48pub union MaybeUninit<T> {
49    uninit: (),
50    value: ManuallyDrop<T>,
51}
52
53impl<T> MaybeUninit<T> {
54    /// Creates a new `MaybeUninit<T>` in an uninitialized state.
55    ///
56    /// Note that dropping a `MaybeUninit<T>` will never call `T`'s drop code.
57    /// It is your responsibility to make sure `T` gets dropped if it got
58    /// initialized.
59    ///
60    /// See the [type-level documentation][MaybeUninit] for some examples.
61    ///
62    /// # Example
63    ///
64    /// ```
65    /// use musli_zerocopy::mem::MaybeUninit;
66    ///
67    /// let mut v: MaybeUninit<u32> = MaybeUninit::uninit();
68    /// ```
69    pub const fn uninit() -> Self {
70        MaybeUninit { uninit: () }
71    }
72
73    /// Write a value to the current location being pointed to.
74    ///
75    /// Note that we cannot return a reference to the written value, because it
76    /// might not be aligned.
77    ///
78    /// We can however return the underlying bytes that were written because of
79    /// this type, since they are now initialized.
80    ///
81    /// See the [type-level documentation][MaybeUninit] for some examples.
82    ///
83    /// # Example
84    ///
85    /// Writing to an uninitialized location on the stack:
86    ///
87    /// ```
88    /// use musli_zerocopy::mem::MaybeUninit;
89    ///
90    /// let mut v: MaybeUninit<u32> = MaybeUninit::uninit();
91    /// assert_eq!(v.write(&10u32.to_le()), &[10, 0, 0, 0]);
92    /// ```
93    #[inline]
94    pub fn write(&mut self, value: &T) -> &mut [u8]
95    where
96        T: ZeroCopy,
97    {
98        unsafe {
99            let ptr = NonNull::new_unchecked(self as *mut Self as *mut u8);
100            buf::store_unaligned(ptr, value);
101            slice::from_raw_parts_mut(ptr.as_ptr(), size_of::<T>())
102        }
103    }
104}
105
106impl<T> fmt::Debug for MaybeUninit<T> {
107    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
108        f.debug_struct("MaybeUninit").finish_non_exhaustive()
109    }
110}
111
112impl<T> Pointee for MaybeUninit<T>
113where
114    T: Pointee,
115{
116    type Metadata = T::Metadata;
117    type Stored<O>
118        = T::Stored<O>
119    where
120        O: Size;
121
122    #[inline]
123    fn try_from_metadata<O>(metadata: Self::Metadata) -> Option<Self::Stored<O>>
124    where
125        O: Size,
126    {
127        T::try_from_metadata(metadata)
128    }
129}
musli_zerocopy/mem/maybe_uninit.rs

musli_zerocopy/mem/
maybe_uninit.rs
