[−][src]Struct static_alloc::uninit::Uninit
Points to an uninitialized place but would otherwise be a valid reference.
This is a &mut
-like struct that is somewhat of a pendant to MaybeUninit
. It makes it
possible to deal with uninitialized allocations without requiring an unsafe
block
initializing them and offers a much safer interface for partial initialization and layout
calculations than raw pointers.
Note that it also supports slices which means it does not use MaybeUninit
internally but
offers conversion where necessary.
Usage
The basic usage is also interacting with MaybeUninit
:
use core::mem::MaybeUninit; use static_alloc::Uninit; let mut alloc: MaybeUninit<MyStruct> = MaybeUninit::uninit(); let uninit = Uninit::from_maybe_uninit(&mut alloc); // notice: no unsafe let instance: &mut MyStruct = uninit.init(MyStruct::default());
But since we are working on arbitrary uninitialized memory it is also possible to reuse the
structure for completely arbitrary other types. Just note that there is no integrated mechanis
for calling Drop
.
use core::mem::MaybeUninit; use static_alloc::Uninit; // Just a generic buffer. let mut alloc: MaybeUninit<[u32; 1024]> = MaybeUninit::uninit(); let uninit = Uninit::from_maybe_uninit(&mut alloc); // Now use the first `u32` for a counter: let mut counter = uninit.cast().unwrap(); let mut tail = counter.split_to_fit(); let counter: &mut u32 = counter.init(0); // And some more for a few `u64`. // Note that these are not trivially aligned, but `Uninit` does that for us. let mut values = tail.split_cast().unwrap(); // No more use, so don't bother with `split_to_fit` and just `init`. let values: &mut [u64; 2] = values.init([0xdead, 0xbeef]);
Methods
impl<'_> Uninit<'_, ()>
[src]
pub unsafe fn from_memory(ptr: NonNull<()>, len: usize) -> Self
[src]
Create a uninit pointer from raw memory.
Safety
A valid allocation must exist at the pointer with length at least len
. There must be no
references aliasing the memory location, and it must be valid to write uninitialized bytes
into arbitrary locations of the region.
In particular, it is UB to create this from a reference to a variable of a type for
which a completely uninitialized content is not valid. The standard type for avoiding the
UB is core::mem::MaybeUninit
.
When in doubt, refactor code such that utilization of from_maybe_uninit
is possible.
pub fn split_layout(&mut self, layout: Layout) -> Option<Self>
[src]
Split so that the second part fits the layout.
Return Ok
if this is possible in-bounds and Err
if it is not.
impl<'a> Uninit<'a, ()>
[src]
pub fn split_cast<U>(&mut self) -> Option<Uninit<'a, U>>
[src]
Split so that the tail is aligned and valid for a U
.
Return Ok
if this is possible in-bounds (aligned and enough room for at least one U
)
and Err
if it is not. The first tuple element is the Uninit
pointing to the skipped
memory.
pub fn split_slice<U>(&mut self) -> Option<Uninit<'a, [U]>>
[src]
Split so that the tail is aligned for a slice [U]
.
Return Ok
if this is possible in-bounds and Err
if it is not. The first tuple element
is the Uninit
pointing to the skipped memory.
The length of the slice is the arbitrary amount that fits into the tail of the allocation.
Note that the length always fulfills the safety requirements for slice::from_raw_parts
since the Uninit
must be contained in a single allocation.
impl<'_, T> Uninit<'_, T>
[src]
pub fn invent_for_zst() -> Self
[src]
Invent a new uninit allocation for a zero-sized type (ZST).
Panics
This method panics when the type parameter is not a zero sized type.
impl<'a, T> Uninit<'a, T>
[src]
pub fn from_maybe_uninit(mem: &'a mut MaybeUninit<T>) -> Self
[src]
Create an initializable pointer to the inner bytes of a MaybeUninit
.
pub fn split_at_byte(&mut self, at: usize) -> Option<Uninit<'a, ()>>
[src]
Split the uninit slice at a byte boundary.
Return Ok
if the location is in-bounds and Err
if it is out of bounds.
pub fn cast<U>(self) -> Result<Uninit<'a, U>, Self>
[src]
Try to cast to an Uninit
for another type.
Return Ok
if the current Uninit
is suitably aligned and large enough to hold at least
one U
and Err
if it is not. Note that the successful result points to unused remaining
memory behind where the instance can be placed.
Use split_to_fit
to get rid of surplus memory at the end.
pub fn cast_slice<U>(self) -> Result<Uninit<'a, [U]>, Self>
[src]
Try to cast to an Uninit
for a slice type.
Return Ok
if the current Uninit
is suitably aligned and large enough to hold at least
one U
and Err
if it is not. Note that the successful result points to unused remaining
memory behind where the instances can be placed.
pub fn split_to_fit(&mut self) -> Uninit<'a, ()>
[src]
Split off the tail that is not required for holding an instance of T
.
This operation is idempotent.
pub fn init(self, val: T) -> &'a mut T
[src]
Initialize the place and return a reference to the value.
impl<'a, T> Uninit<'a, [T]>
[src]
pub fn empty() -> Self
[src]
Creates a pointer to an empty slice.
pub const fn as_begin_ptr(&self) -> *mut T
[src]
Get the pointer to the first element of the slice.
If the slice would be empty then the pointer may be the past-the-end pointer as well.
pub fn capacity(&self) -> usize
[src]
Calculate the theoretical capacity of a slice in the pointed-to allocation.
pub fn split_at(&mut self, at: usize) -> Option<Self>
[src]
Split the slice at an index.
This is the pointer equivalent of slice::split_at
.
pub fn shrink_to_fit(&mut self) -> Uninit<'a, ()>
[src]
Get the trailing bytes behind the slice.
The underlying allocation need not be a multiple of the slice element size which may leave
unusable bytes. This splits these unusable bytes into an untyped Uninit
which can be
reused arbitrarily.
This operation is idempotent.
pub fn split_first(&mut self) -> Option<Uninit<'a, T>>
[src]
Split the first element from the slice.
This is the pointer equivalent of slice::split_first
.
pub fn split_last(&mut self) -> Option<Uninit<'a, T>>
[src]
Split the last element from the slice.
This is the pointer equivalent of slice::split_last
.
impl<'a, T: ?Sized> Uninit<'a, T>
[src]
pub fn as_memory(self) -> Uninit<'a, ()>
[src]
View the same uninit as untyped memory.
pub fn borrow(&self) -> UninitView<T>
[src]
Borrow a view of the Uninit
region.
This is the equivalent of &*mut_ref as *const _
but never runs afoul of accidentally
creating an actual reference.
pub fn borrow_mut(&mut self) -> Uninit<T>
[src]
Borrow the Uninit
region for a shorter duration.
This is the equivalent of &mut *mut_ref as *mut _
but never runs afoul of accidentally
creating an actual reference.
pub const fn size(&self) -> usize
[src]
Get the byte size of the total allocation.
pub const fn as_ptr(&self) -> *mut T
[src]
Acquires the underlying *mut pointer.
pub const fn as_non_null(&self) -> NonNull<T>
[src]
Acquires the underlying pointer as a NonNull
.
pub unsafe fn as_ref(&self) -> &T
[src]
Dereferences the content.
The resulting lifetime is bound to self so this behaves "as if" it were actually an
instance of T that is getting borrowed. If a longer lifetime is needed, use into_ref
.
pub unsafe fn as_mut(&mut self) -> &mut T
[src]
Mutably dereferences the content.
The resulting lifetime is bound to self so this behaves "as if" it were actually an
instance of T that is getting borrowed. If a longer lifetime is needed, use into_mut
.
pub unsafe fn into_ref(self) -> &'a T
[src]
Turn this into a reference to the content.
pub unsafe fn into_mut(self) -> &'a mut T
[src]
Turn this into a mutable reference to the content.
Trait Implementations
impl<'_, T: ?Sized> Debug for Uninit<'_, T>
[src]
impl<'a, T> From<&'a mut MaybeUninit<T>> for Uninit<'a, T>
[src]
fn from(mem: &'a mut MaybeUninit<T>) -> Self
[src]
impl<'_, T> Default for Uninit<'_, [T]>
[src]
Auto Trait Implementations
impl<'a, T: ?Sized> Unpin for Uninit<'a, T> where
T: Unpin,
T: Unpin,
impl<'a, T> !Send for Uninit<'a, T>
impl<'a, T> !Sync for Uninit<'a, T>
Blanket Implementations
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,