Struct contiguous_mem::ContiguousMemoryStorage

pub struct ContiguousMemoryStorage<Impl: ImplDetails = ImplDefault> { /* private fields */ }

A memory container for efficient allocation and storage of contiguous data.

This collection manages a contiguous block of memory, allowing for storage of arbitrary data types while ensuring that stored items are placed adjacently and ensuring they’re properly alligned.

Type argument Impl specifies implementation details for the behavior of this struct. This struct also implements StoreData for all of the details which specifies underlying logic for storing items.

Note that this structure is a smart abstraction over underlying data, copying it creates a copy which represents the same internal state.

Implementations

impl<Impl: ImplDetails> ContiguousMemoryStorage<Impl>

pub fn new(capacity: usize) -> Self

Creates a new ContiguousMemory instance with the specified capacity, aligned as platform dependant alignment of usize.

Examples found in repository

examples/default_impl.rs (line 10)

fn main() {
    // Create a ContiguousMemory instance with a capacity of 1024 bytes and 1-byte alignment
    let mut memory = ContiguousMemory::new(1024);

    // Store data in the memory container
    let data = Data { value: 42 };
    let stored_number: ContiguousMemoryRef<u64> = memory.store(22u64);
    let stored_data: ContiguousMemoryRef<Data> = memory.store(data);

    // Retrieve and use the stored data
    assert_eq!(*stored_data.get(), data);
    assert_eq!(*stored_number.get(), 22);
}

examples/unsafe_impl.rs (line 10)

fn main() {
    // Create a ContiguousMemory instance with a capacity of 1024 bytes and 1-byte alignment
    let mut memory = UnsafeContiguousMemory::new(1024);

    // Store data in the memory container
    let data = Data { value: 42 };

    let stored_number: *mut u64 = memory
        .store(22u64)
        .expect("there should be enough space to store a number");
    let stored_data: *mut Data = memory
        .store(data)
        .expect("there should be enough space to store Data");

    // Retrieve and use the stored data
    unsafe {
        assert_eq!(*stored_data, data);
        assert_eq!(*stored_number, 22);
    }
}

examples/sync_impl.rs (line 9)

fn main() {
    let storage = SyncContiguousMemory::new(4096);

    let mut sent_storage = storage.clone();
    let writer_one =
        std::thread::spawn(move || sent_storage.store(22u64).expect("unable to store number"));

    let data = Data { value: 42 };

    let mut sent_storage = storage.clone();
    let writer_two = std::thread::spawn(move || {
        sent_storage
            .store(Data { value: 42 })
            .expect("unable to store Data")
    });

    let stored_number: SyncContiguousMemoryRef<u64> =
        writer_one.join().expect("unable to join number thread");
    let mut stored_number_clone = stored_number.clone();
    let stored_data: SyncContiguousMemoryRef<Data> =
        writer_two.join().expect("unable to join Data thread");

    let number_ref = stored_number
        .get()
        .expect("number ref poisoned on first use");
    let stored_data = stored_data.get().expect("Data ref poisoned on first use");

    // note that number is still locked here
    assert!(
        stored_number_clone.try_get_mut().is_err(),
        "number reference should not be writable as the number is currently borrowed"
    );

    assert_eq!(*number_ref, 22);
    assert_eq!(*stored_data, data);
}

pub fn new_aligned( capacity: usize, alignment: usize ) -> Result<Self, LayoutError>

Creates a new ContiguousMemory instance with the specified capacity and alignment.

pub fn get_base(&self) -> Impl::LockResult<*mut u8>

Returns the base address (*mut u8) of the allocated memory.

Errors

For concurrent implementation this function can return LockingError::Poisoned if the mutex holding the base address has been poisoned.

pub fn get_capacity(&self) -> usize

Returns the current capacity of the memory container.

The capacity represents the size of the memory block that has been allocated for storing data. It may be larger than the amount of data currently stored within the container.

pub fn get_layout(&self) -> Layout

Returns the layout of the memory region containing stored data.

pub fn resize( &mut self, new_capacity: usize ) -> Result<Option<*mut u8>, ContiguousMemoryError>

Resizes the memory container to the specified new_capacity, optionally returning the new base address of the stored items.

Shrinking the container is generally performed in place by freeing tailing memory space, but growing it can move the data in memory to find a location that can fit it.

Unsafe implementation should match on the returned value and update any existing pointers accordingly.

Errors

This function can return the following errors:

• ContiguousMemoryError::Unshrinkable: Returned when attempting to shrink the memory container, but the stored data prevents the container from being shrunk to the desired capacity.

• ContiguousMemoryError::Lock: Returned if the mutex holding the base address or the AllocationTracker is poisoned.

pub fn shrink_to_fit(&mut self) -> Result<(), ContiguousMemoryError>

Shrinks the allocated memory to fit the currently stored data.

pub fn store<T: StoreRequirements>( &mut self, value: T ) -> <Impl as StorageDetails>::StoreResult<T>where Self: StoreData<Impl>,

Stores a value of type T in the contiguous memory block.

Value type is used to deduce type size and returned reference dropping behavior.

Returned value is implementation specific:

• For concurrent implementation it is Result<SyncContiguousMemoryRef<T>, LockingError>,
• For default implementation it is ContiguousMemoryRef<T>,
• For fixed implementation it is Result<*mut u8, ContiguousMemoryError>.

Examples found in repository

examples/default_impl.rs (line 14)

fn main() {
    // Create a ContiguousMemory instance with a capacity of 1024 bytes and 1-byte alignment
    let mut memory = ContiguousMemory::new(1024);

    // Store data in the memory container
    let data = Data { value: 42 };
    let stored_number: ContiguousMemoryRef<u64> = memory.store(22u64);
    let stored_data: ContiguousMemoryRef<Data> = memory.store(data);

    // Retrieve and use the stored data
    assert_eq!(*stored_data.get(), data);
    assert_eq!(*stored_number.get(), 22);
}

examples/unsafe_impl.rs (line 16)

fn main() {
    // Create a ContiguousMemory instance with a capacity of 1024 bytes and 1-byte alignment
    let mut memory = UnsafeContiguousMemory::new(1024);

    // Store data in the memory container
    let data = Data { value: 42 };

    let stored_number: *mut u64 = memory
        .store(22u64)
        .expect("there should be enough space to store a number");
    let stored_data: *mut Data = memory
        .store(data)
        .expect("there should be enough space to store Data");

    // Retrieve and use the stored data
    unsafe {
        assert_eq!(*stored_data, data);
        assert_eq!(*stored_number, 22);
    }
}

examples/sync_impl.rs (line 13)

fn main() {
    let storage = SyncContiguousMemory::new(4096);

    let mut sent_storage = storage.clone();
    let writer_one =
        std::thread::spawn(move || sent_storage.store(22u64).expect("unable to store number"));

    let data = Data { value: 42 };

    let mut sent_storage = storage.clone();
    let writer_two = std::thread::spawn(move || {
        sent_storage
            .store(Data { value: 42 })
            .expect("unable to store Data")
    });

    let stored_number: SyncContiguousMemoryRef<u64> =
        writer_one.join().expect("unable to join number thread");
    let mut stored_number_clone = stored_number.clone();
    let stored_data: SyncContiguousMemoryRef<Data> =
        writer_two.join().expect("unable to join Data thread");

    let number_ref = stored_number
        .get()
        .expect("number ref poisoned on first use");
    let stored_data = stored_data.get().expect("Data ref poisoned on first use");

    // note that number is still locked here
    assert!(
        stored_number_clone.try_get_mut().is_err(),
        "number reference should not be writable as the number is currently borrowed"
    );

    assert_eq!(*number_ref, 22);
    assert_eq!(*stored_data, data);
}

pub fn can_store<T: StoreRequirements>( &self, value: &T ) -> Result<bool, ContiguousMemoryError>

Returns true if the provided value can be stored.

If the AllocationTracker can’t be immutably accesed, a ContiguousMemoryError::TrackerInUse error is returned.

For concurrent implementation a ContiguousMemoryError::Lock is returned under same conditions.

Unsafe implementation never fails.

impl ContiguousMemoryStorage<ImplUnsafe>

pub unsafe fn free_typed<T>(&mut self, position: *mut T)

Allows freeing a memory range stored at provided position.

Type of the position pointer T determines the size of the freed chunk.

pub unsafe fn free<T>(&mut self, position: *mut T, size: usize)

Allows freeing a memory range stored at provided position with the specified size.

Trait Implementations

impl<Impl: ImplDetails> Clone for ContiguousMemoryStorage<Impl>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Impl: ImplDetails> Deref for ContiguousMemoryStorage<Impl>

type Target = ContiguousMemoryState<Impl>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl StoreData<ImplConcurrent> for ContiguousMemoryStorage<ImplConcurrent>

unsafe fn store_data<T: StoreRequirements>( &mut self, data: *mut T, layout: Layout ) -> Result<SyncContiguousMemoryRef<T>, LockingError>

Returns a SyncContiguousMemoryRef pointing to the stored value, or a LockingError::Poisoned error when the AllocationTracker associated with the memory container is poisoned.

impl StoreData<ImplDefault> for ContiguousMemoryStorage<ImplDefault>

unsafe fn store_data<T: StoreRequirements>( &mut self, data: *mut T, layout: Layout ) -> ContiguousMemoryRef<T>

Returns a ContiguousMemoryRef pointing to the stored value.

impl StoreData<ImplUnsafe> for ContiguousMemoryStorage<ImplUnsafe>

unsafe fn store_data<T: StoreRequirements>( &mut self, data: *mut T, layout: Layout ) -> Result<*mut T, ContiguousMemoryError>

Returns a raw pointer (*mut T) to the stored value or a ContiguousMemoryError::NoStorageLeft indicating that the container couldn’t store the provided data with current size.

Memory block can still be grown by calling ContiguousMemory::resize, but it can’t be done automatically as that would invalidate all the existing pointers without any indication.