Struct inplace_it::UninitializedSliceMemoryGuard

[+] Show declaration

pub struct UninitializedSliceMemoryGuard<'a, T> { /* fields omitted */ }

[−] Expand description

Guard-struct used to own uninitialized memory and provide functions for initializing it. Usually, you should not use this struct to handle your memory.

Initializing functions spawns SliceMemoryGuard which will provide access to initialized memory. It also means memory can be used again after SliceMemoryGuard is dropped.

Safety

If you use this struct manually, remember: &mut [MaybeUninit<T>]'s content will be overwriten while initialization. So it is not safe to apply this struct to already initialized data and it can lead to memory leaks.

Example

use inplace_it::UninitializedSliceMemoryGuard;
use std::mem::MaybeUninit;

// Placing uninitialized memory
let mut memory: [MaybeUninit<usize>; 100] = unsafe { MaybeUninit::uninit().assume_init() };
// Initializing guard
let mut uninit_memory_guard = unsafe { UninitializedSliceMemoryGuard::new(&mut memory) };

{
    // Initializing memory
    let mut memory_guard = uninit_memory_guard
        // we need to call .borrow() because out init-API consumes uninit-guard
        .borrow()
        // then passing initialize closure and the guard is ok
        .init(|index| index * 2);
    // For now, memory contains content like [0, 2, 4, 6, ..., 196, 198]

    // Using memory
    // Sum of [0, 2, 4, 6, ..., 196, 198] = sum of [0, 1, 2, 3, ..., 98, 99] * 2 = ( 99 * (99+1) ) / 2 * 2
    let sum: usize = memory_guard.iter().sum();
    assert_eq!(sum, 99 * 100);
    // memory_guard dropped here
}

// uninit_memory_guard is available again now

{
    // Initializing memory
    let mut memory_guard = uninit_memory_guard.init(|index| index * index);
    // For now, memory contains content like [0, 1, 4, 9, ..., 9604, 9801]

    // Using memory
    // Sum of [0, 1, 4, 9, ..., 9604, 9801] = 99 * (99 + 1) * (2 * 99 + 1) / 6
    let sum: usize = memory_guard.iter().sum();
    assert_eq!(sum, 99 * (99 + 1) * (2 * 99 + 1) / 6);
    // memory_guard dropped here
}

Implementations

impl<'a, T> UninitializedSliceMemoryGuard<'a, T>[−]

pub unsafe fn new(memory: &'a mut [MaybeUninit<T>]) -> Self[−]

Initialize memory guard

pub fn len(&self) -> usize[−]

Get the length of memory slice

pub fn slice(self, range: impl RangeBounds<usize>) -> Self[−]

Construct new memory guard with new bounds.

Can be used to shrink memory.

Panics

Panic can be reached when given range is out of memory's range.

pub fn init(self, init: impl FnMut(usize) -> T) -> SliceMemoryGuard<'a, T>[−]

Initialize memory and make new guard of initialized memory. Given init closure will be used to initialize elements of memory slice.

pub fn init_copy_of(self, source: &[T]) -> SliceMemoryGuard<'a, T> where
    T: Clone, [−]

Initialize memory and make new guard of initialized memory. Given source slice will be used to initialize elements of memory slice. Returned guard will contain sliced memory to source's length.

Panics

Panic can be reached when given source's range is out of memory's range.

pub fn init_with_iter(
    self,
    iter: impl ExactSizeIterator<Item = T>
) -> SliceMemoryGuard<'a, T>[−]

Initialize memory and make new guard of initialized memory. Given iter exact-size iterator will be used to initialize elements of memory slice. Returned guard will contain sliced memory to iter's length.

Panics

Panic can be reached when given iter's length is out of memory's range.

pub fn borrow(&mut self) -> UninitializedSliceMemoryGuard<'_, T>[−]

Create new uninit memory guard with less or equal lifetime to original guard's lifetime. This function should be used to reuse memory because init-API consumes the guard.