contiguous_mem

contiguous_mem is space optimized a vector like collection that can store entries of varying layouts close in memory while retaining type information at the reference level.

Use Case

^{* Both Vec and ContiguousMemory have one level of indirection that's not shown for sake of simplicity.}

You need to store several different types and ensure their close proximity on the heap to reduce cache misses, but which/how many is determined at runtime.

Key Features

• no_std support!
• Interface similar to Vec.
• Support for dynamic resizing of allocated memory while keeping the existing references functional (for safe implementations).
• Exhaustively tested with Miri.
• Limited downstream dependencies (only polyfills).
  • sptr is used as polyfill for Strict Provenance and required for MIRI.
  • allocator-api2 is used as polyfill for the allocator API.

Getting Started

Add the crate to your dependencies:

[dependencies]
contiguous_mem = { version = "0.5" }

Disable default features (std feature) for use in no_std environments:

[dependencies]
contiguous_mem = { version = "0.5", default-feature = false, features = ["unsafe_impl"] }

Features

• no_std - enables no_std dependencies for atomics, mutexes and rwlocks
• debug - enables derive(Debug) on structures unrelated to error handling
• ptr_metadata <nightly> - allows casting references into dyn Trait
• error_in_core <nightly> - enables support for core::error::Error in no_std environment
• unsafe_impl (default) - enables UnsafeContiguousMemory

Usage

use contiguous_mem::*;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Data {
    value: u32,
}

fn main() {
    // Create a ContiguousMemory instance
    let mut memory = ContiguousMemory::new();

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

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

_{* Note that reference types returned by store are inferred and only shown here for demonstration purposes.}

Returned references have semantics similar to RefCell.

For more usage examples see the examples directory.

Stability

This crate has almost complete test coverage and is tested with Miri. It doesn't rely on any weird language quirks, but it does deal with memory management.

There's a lot of unsafe code due to the nature of the crate, but again, it's covered by tests and Miri.

Alternatives

• manually managing memory to ensure contiguous placement of data
  • prone to errors and requires unsafe code
• multiple levels of indirection (Vec<Box<dyn Trait>>)
• for storing types with uniform Layout, when you only need to erase their types at the container level see:
  • any_vec
  • type_erased_vec
  • untyped_vec
• using a custom allocator like blink-alloc to ensure contiguous placement of data
  • requires allocator_api feature
  • blink-alloc provides a similar functionality as this crate without the allocator_api feature; intended for use in loops so it doesn't support freeing some values while retaining other

Contributions

Contributions are welcome, feel free to create an issue or a pull request.

All contributions to the project are licensed under the Zlib/MIT/Apache 2.0 license unless you explicitly state otherwise.

License

This project is licensed under Zlib, MIT, or Apache-2.0 license, choose whichever suits your use case the best.