Struct heaparray::mem_block::MemBlock

#[repr(C)]
pub struct MemBlock<E, L = ()> { /* fields omitted */ }

An array block that can hold arbitrary information, and cannot be constructed on the stack. The E type can be repeated an arbitrary number of times, and the L type can be repeated exactly once.

It's not recommended to use this directly; instead, use the pointer types that refer to these, namely HeapArray, FatPtrArray, and ThinPtrArray.

Invariants

The code for this struct does little to no runtime checks for validity; thus, you need to do them yourself. Length checks, runtime validity checks, etc. all need to be done at runtime before using the methods associated with this type, as forgetting to do so leads to undefined behavior (likely a segmentation fault or an invalid pointer dereference). To avoid these errors, you can instead use the safe API provided by the ThinPtrArray and FatPtrArray structs, or by the HeapArray struct, which internally is implemented as a FatPtrArray.

Methods

impl<E, L> MemBlock<E, L>

pub fn memory_layout(len: usize) -> (usize, usize)

Get size and alignment of the memory that a block of length len would need.

pub unsafe fn dealloc(&mut self, len: usize)

Deallocates a reference to this struct, as well as all objects contained in it. This function is safe given that the following preconditions hold:

• The reference &self is valid, and points to a valid instance of this type
• The memory block pointed to by &self was initialized with length of len
• The operation of dereferencing an element at index i, where 0 <= i < len, accesses valid memory that has been properly initialized. This is NOT checked at runtime.

pub unsafe fn dealloc_lazy(&mut self, len: usize)

Deallocates a reference to this struct, without running the destructor of the elements it contains. This function is safe given that the following preconditions hold:

• The reference &self is valid, and points to a valid instance of this type
• The memory block pointed to by &self was initialized with length of len

This function may leak memory; be sure to run destructors on all initialized elements in this block before calling this method, as they may in accessible afterwards if you don't.

pub unsafe fn new<'a>(label: L, len: usize) -> *mut Self

Returns a pointer to a new memory block on the heap with an initialized label. Does not initialize memory, so use with care.

If you use this function, remember to prevent the compiler from running the destructor for the memory wasn't initialized. i.e. something like this:

use heaparray::mem_block::MemBlock;
use core::mem;
let len = 100;
let block = unsafe { &mut *MemBlock::<usize, ()>::new((), len) };
for i in 0..len {
    let item = i * i;
    let garbage = mem::replace(unsafe { block.get(i) }, item);
    mem::forget(garbage);
}

pub fn new_init<F>(label: L, len: usize, func: F) -> *mut Self where
    F: FnMut(&mut L, usize) -> E, 

Returns a pointer to a labelled memory block, with elements initialized using the provided function. Function is safe, because the following invariants will always hold:

• A memory access block.get(i) where 0 <= i < len will always be valid.
• A memory access block.label will always be valid.

However, note that deallocating the resulting block can never be safe; there is not guarrantee provided by the type system that the block you deallocate will have the length that you assume it has.

pub unsafe fn get<'a>(&'a self, idx: usize) -> &'a mut E

Gets a mutable reference to the element at the index idx in this memory block. This function will return a valid reference given that the following preconditions hold:

• The reference &self is valid, and points to a valid instance of this type
• The memory block pointed to by &self was initialized with a len of at least idx + 1
• The element at index idx was initialized; this can be acheived by calling MemBlock::new_init(label, len, || { /* closure */ }). or by initializing the values yourself.

pub unsafe fn get_label<'a>(&'a self) -> &'a mut L

Get the label associated with this memory block.

Important traits for MemBlockIter<E, L>

impl<E, L> Iterator for MemBlockIter<E, L> type Item = E;

pub unsafe fn iter(&self, len: usize) -> MemBlockIter<E, L>

Generates an iterator from this memory block, which is inclusive on the start index and exclusive on the end index. The iterator operates on the preconditions that:

• The operation of dereferencing an element at index i, where 0 <= i < len, accesses valid memory that has been properly initialized. This is NOT checked at runtime.

This function is unsafe because not meeting any of the above conditions results in undefined behavior. Additionally, the iterator that's created can potentially take ownership, and it's your job to prove that doing so is a valid operation.

pub unsafe fn get_slice<'a>(&'a self, start: usize, end: usize) -> &'a mut [E]

Generates a slice into this memory block. The following invariants must hold:

• Mutual exclusivity of mutable slices; for every element in the block, there can be at most one mutable reference to it at any given time.
• start must be less than or equal to end. This is checked at runtime unless this crate is build with the feature no-asserts.
• The operation of dereferencing an element at index i, where start <= i < end, accesses valid memory that has been properly initialized. This is NOT checked at runtime.

pub unsafe fn as_slice<'a>(&'a self, len: usize) -> &'a mut [E]

Generates a slice into this memory block. The following invariants must hold:

• The operation of dereferencing an element at index i, where 0 <= i < len, accesses valid memory that has been properly initialized. This is NOT checked at runtime.

impl<E, L> MemBlock<E, L> where
    E: Clone,
    L: Clone, 

pub unsafe fn clone<'a, 'b>(&'a self, len: usize) -> &'b mut Self

Clones all the elements in this memory block, as well as the label. This function is safe given that the following preconditions are true:

• The reference &self is valid, and points to a valid instance of this type
• The memory block pointed to by &self was initialized with length of len
• The element at index i was initialized, where 0 <= i < len, for all i
• The operation of dereferencing an element at index i, where 0 <= i < len, accesses valid memory that has been properly initialized. This is NOT checked at runtime.