Struct possibly_uninit::Out

pub struct Out<'a, T>(_);

Mutable reference wrapper that only allows writing valid values to the memory location.

This is used for values that might be borowed from either T or MaybeUninit<T>.

One would normally expect this to be &mut MaybeUninit<T>, however, that wouldn’t be sound. Consider this code:

use core::mem::MaybeUninit;
 
fn cast_mut<T>(val: &mut T) -> &mut MaybeUninit<T> {
    unsafe {
        core::mem::transmute(val)
    }
}
 
// No unsafe code here
fn main() {
    let mut message = "Hello world!".to_string();
    core::mem::replace(cast_mut(&mut message), MaybeUninit::uninit());
    println!("This is now garbage: {}", message);
}

The code above triggers UB. Thus the users of the reference must be prevented from writing invalid values into the memory location. That’s only possible by creating a newtype like this one.

While the newtype itself doesn’t track initializedness, so its use may be limited in safe code, it’s a base building block allowing sound implementations of wrappers tracking initializedness.

Implementations

impl<'a, T> Out<'a, T>

pub fn write(self, value: T) -> &'a mut T

Writes a valid value to given memory location, initializing it.

pub fn write_mut(&mut self, value: T) -> &mut T

Writes a valid value to given memory location, initializing it.

This method is same as write, it just reborows the reference instead of consuming it.

pub unsafe fn into_assume_init(self) -> &'a mut T

Turns the wrapper into reference assuming the value was initialized.

Safety

Calling this function if no value was written is UB.

pub fn as_non_null(&mut self) -> NonNull<T>

Returns mutable non-null pointer to the value.

pub fn as_mut_ptr(&mut self) -> *mut T

Returns mutable raw pointer to the value.

Note that this is in fact non-null, it’s just sometimes more useful than as_non_null.

pub fn write_zeroes(&mut self) -> &mut T where
    T: ZeroValid, 

Overwrites the value with all zeroes.

pub fn into_zeroed(self) -> &'a mut T where
    T: ZeroValid, 

Overwrites the value with all zeroes.

Consumes the referenceto to preserve the lifetime

Trait Implementations

impl<'a, T> BorrowOut<T> for Out<'a, T>

fn borrow_out(&mut self) -> Out<'_, T>

Mutably borrows maybe uninitialized value.

unsafe fn assume_init_mut(&mut self) -> &mut Borrowed

Converts the reference assuming it’s initialized.

fn init(&mut self, item: Borrowed) -> &mut Borrowed

Initializes the memory location with valid value.

fn default_if_needed(&mut self) -> &mut Borrowed where
    Borrowed: Default, 

Overwrites the memory with Default::default() if necessary.

fn zeroed_if_needed(&mut self) -> &mut Borrowed where
    Borrowed: ZeroValid, 

Overwrites the memory with Default::default() if necessary.

impl<'a, T> BorrowUninit<T> for Out<'a, T>

fn borrow_uninit(&self) -> &MaybeUninit<T>

Borrows maybe uninitialized value.

unsafe fn assume_init_ref(&self) -> &Borrowed

Converts the reference assuming it’s initialized.

impl<'a, T> From<&'a mut MaybeUninit<T>> for Out<'a, T>

fn from(value: &'a mut MaybeUninit<T>) -> Self

Performs the conversion.

impl<'a, T> From<&'a mut T> for Out<'a, T>

fn from(value: &'a mut T) -> Self

Performs the conversion.