README.md

contiguous_mem

contiguous_mem streamlines storage and management of data stored in contiguous blocks of memory.

Stability

All versions prior to 1.0.0 are not considered production ready. This is my first crate and there's still a lot of edge cases I didn't get a chance to consider yet.

Prelimenary tests are in place but I don't consider them sufficient to guarantee correctness of behavior.

Key Features

• no_std support!
• Simple and straightforward interface similar to standard containers.
• Support for dynamic resizing of allocated memory keeping the created references functional (for safe implementations).

Specialized implementations

You can pick and choose which implementation suits your use case best allowing you to avoid runtime cost of synchronization and additionally memory cost of safely wrapping referenced data if you don't need it.

Default implementation keeps relative offsets of stored data which are resolved on access.

Use cases

• Storing differently typed/sized data. (example)
• Ensuring stored data is placed adjacently in memory. (example)
  • Note that for this use case implementations other than unsafe aren't ideal for ensuring cache locality as returned references are smart pointers which will be stored elsewhere in memory. Other implementations are however useful for constructing contiguous data from code which would require complicated memory management otherwise.

Tradeoffs

• Works without nightly but leaks data requiring Drop or drop glue, enable ptr_metadata or disable default leak_data feature flag if memory leaks are an issue:
  • ptr_metadata requires nightly,
  • disabling leak_data imposes Copy requirement on stored types.

Getting Started

Add the crate to your dependencies:

[dependencies]
contiguous_mem = { version = "0.4.*" }

Optionally disable the std feature and enable no_std feature to use in no_std environment:

[dependencies]
contiguous_mem = { version = "0.4.*", default-features = false, features = ["no_std"] }

Features

• no_std - enables no_std dependencies for atomics, mutexes and rwlocks
• leak_data (default) - disables Copy requirement for stored types, but any references in stored data will be leaked when the memory container is dropped
• debug - enables derive(Debug) on structures unrelated to error handling
• ptr_metadata <nightly> - enables support for casting returned references into dyn Trait types as well as cleaning up any types that implement Drop or generate drop glue
• error_in_core <nightly> - enables support for core::error::Error in no_std environment

Usage

use contiguous_mem::*;

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

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.push(22u64);
    let stored_data: ContiguousMemoryRef<Data> = memory.push(data);

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

• References have a similar API as RefCell

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

For more usage examples see the examples directory.

Alternatives

• manually managing memory to ensure contiguous placement of data
  • prone to errors and requires unsafe code
• 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 you most.