Struct DHeap 

pub struct DHeap<T: Sized> { /* private fields */ }

A DHeap is a dense heap data structure that efficiently manages memory allocation and deallocation.

The heap has an overhead of 24 bytes per element, and it will never use more memory than what is allocated at any given point in time, no matter which elements are freed and in which order. The linking nature of the indices will always backfill optimally, ensuring that the memory usage is as efficient as possible.

Implementations

impl<T> DHeap<T>

pub fn with_capacity(capacity: usize) -> Self

Creates a new DHeap with a specified initial capacity.

Allocates a buffer with the requested capacity, plus one additional element to account for the Edge. The Edge is a sentinel element used to facilitate certain heap operations.

Arguments

• capacity - The desired initial capacity for the heap.

Panics

Panics if capacity is less than or equal to 1, as the heap requires at least 2 elements to function properly.

pub unsafe fn unsafe_new(&self, v: T) -> DBox<'_, T>

Allocates memory for the given value v in the DHeap and returns a DBox pointing to it.

This function is marked unsafe because it may potentially invalidate existing references if the underlying vector needs to be resized. However, DBox instances will still function correctly.

When the end of the free block list is reached, a new element is pushed during allocation. If this new element requires the vector to grow, any existing references to elements within the dense heap might become invalid. This risk should be carefully considered when using this heap.

One approach to mitigate this risk is to use safe_new().

Safety

Users must ensure that no references to elements within the dense heap are held when calling this function. If references are held, they may become invalid after the function call.

pub fn safe_new(&self, v: T) -> Result<DBox<'_, T>, &'static str>

Provides a safe alternative to DHeap::new() by attempting to allocate memory without resizing the underlying vector.

This function ensures that no existing references will be invalidated during the allocation process, as it only allocates memory when there is available capacity within the reserved memory. However, if the reserved memory is exhausted, an error is returned.

Returns

• Ok(DBox<T>) if the allocation was successful.
• Err(&'static str) if there is no available capacity within the reserved memory.

pub fn size(&self) -> usize

Retrieves the current memory usage of the DHeap.

This function returns the number of elements in the underlying vector, which represents the total memory occupied by the DHeap.

Returns

• A usize representing the memory usage of the DHeap.