Struct aligned_box::AlignedBox

pub struct AlignedBox<T: ?Sized> { /* fields omitted */ }

A wrapper around std::boxed::Box which allows allocating aligned heap memory. An instance of AlignedBox<T> consists of a Box<T> and the std::alloc::Layout that has been used to allocate the referenced memory.

Implementations

impl<T: ?Sized> AlignedBox<T>

pub fn into_raw_parts(from: AlignedBox<T>) -> (*mut T, Layout)

Decompose the AlignedBox into a raw pointer and the layout used during allocation. The caller of this function becomes responsible for proper deallocation of the memory behind the pointer. This can for example be done by reconstructing the AlignedBox using AlignedBox::from_raw_parts.

pub unsafe fn from_raw_parts(ptr: *mut T, layout: Layout) -> AlignedBox<T>

Construct an AlignedBox from a raw pointer and the layout that has been used to allocate the memory behind that pointer. After calling this function, the pointer is owned by the AlignedBox. In particular, the memory will be freed when the AlignedBox is dropped. This is only safe if the given layout is the same as the one that was used during memory allocation.

Safety

The function is unsafe because improper use can lead to issues, such as double-free. Also, behavior is undefined if the given layout does not correspond to the one used for allocation.

impl<T> AlignedBox<T>

pub fn new(alignment: usize, value: T) -> Result<AlignedBox<T>, Box<dyn Error>>

Store value of type T on the heap, making sure that it is aligned to a multiple of alignment. It is also checked if alignment is a valid alignment for type T or increased to a valid alignment otherwise.

Example

Place value 17 of type i32 on the heap, aligned to 64 bytes:

use aligned_box::AlignedBox;

let b = AlignedBox::<i32>::new(64, 17);

impl<T: Default> AlignedBox<[T]>

pub fn slice_from_default(
    alignment: usize,
    nelems: usize
) -> Result<AlignedBox<[T]>, Box<dyn Error>>

Allocate memory for nelems values of type T on the heap, making sure that it is aligned to a multiple of alignment. All values are initialized by the default value of type T. It is also checked if alignment is a valid alignment for type T or increased to a valid alignment otherwise.

Example

Allocate memory for 1024 values of type f32 on the heap, aligned to 128 bytes. Values are initialized by their default value:

use aligned_box::AlignedBox;

let b = AlignedBox::<[f32]>::slice_from_default(128, 1024);

pub fn realloc_with_default(
    &mut self,
    nelems: usize
) -> Result<(), Box<dyn Error>>

Resize allocated memory to fit nelem values of type T. The original alignment requested when creating the AlignedBox will still be obeyed. If nelem is larger than the current amount of stored elements, the newly allocated elements will be initialized with the default value of type T. If nelem is smaller than the current amount of stored elements, any excess elements will be dropped. In case realloc fails, those dropped elements will be reinitialized with the default value of type T.

Example

Create an AlignedBox::<f32> with 1024 elements. Extend to 2048 elements. Initialize all new elements by the default value of f32, i.e., 0.0.

use aligned_box::AlignedBox;

let mut b = AlignedBox::<[f32]>::slice_from_default(128, 1024).unwrap();
b.realloc_with_default(2048);

impl<T: Copy> AlignedBox<[T]>

pub fn slice_from_value(
    alignment: usize,
    nelems: usize,
    value: T
) -> Result<AlignedBox<[T]>, Box<dyn Error>>

Allocate memory for nelems values of type T on the heap, making sure that it is aligned to a multiple of alignment. All values are initialized by copies of value. It is also checked if alignment is a valid alignment for type T or increased to a valid alignment otherwise.

Example

Allocate memory for 1024 values of type f32 on the heap, aligned to 128 bytes. All values are initialized with PI:

use aligned_box::AlignedBox;

let b = AlignedBox::<[f32]>::slice_from_value(128, 1024, std::f32::consts::PI);

pub fn realloc_with_value(
    &mut self,
    nelems: usize,
    value: T
) -> Result<(), Box<dyn Error>>

Resize allocated memory to fit nelem values of type T. The original alignment requested when creating the AlignedBox will still be obeyed. If nelem is larger than the current amount of stored elements, the newly allocated elements will be initialized with the value given as argument to this function. If nelem is smaller than the current amount of stored elements, any excess elements will be dropped. In case realloc fails, those dropped elements will be reinitialized with the value given to this function.

Example

Create an AlignedBox::<f32> with 1024 elements. Extend to 2048 elements. Initialize all new elements by 3.14.

use aligned_box::AlignedBox;

let mut b = AlignedBox::<[f32]>::slice_from_default(128, 1024).unwrap();
b.realloc_with_value(2048, 3.14);

Trait Implementations

impl<T: Clone + ?Sized> Clone for AlignedBox<T>

fn clone(&self) -> Self

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: ?Sized> Deref for AlignedBox<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: ?Sized> DerefMut for AlignedBox<T>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<T: ?Sized> Drop for AlignedBox<T>

fn drop(&mut self)

Executes the destructor for this type.