Lib.rs

Arena storage with bells and whistles

Arena storage with its own basic allocator, managed drop order, efficient and optional drop execution, universal string, list, array, and custom structure/data support.

See more comprehensive writeup in crate documentation.

Some idea of how the usage looks like:

use memur::{Memory, Arena, UStr};

fn main() {
    // memory pool which can be shared between threads
    let mem = Memory::new(); 

    {
        let arena = Arena::new(&mem).unwrap();
    
        // Zero-terminated utf-8 string that does not need 
        // to be dropped:
        let text = UStr::from_str(&arena, "Hello").unwrap();

        assert_eq!("Hello", &text);

        // Since it is zero-terminated, 
        // it can be used in C APIs without conversion:
        assert_eq!(unsafe { CStr::from_bytes_with_nul_unchecked(b"Hello\n") }, &text);

        // Simple struct wrapper, items added this way end up
        // near each other in memory:
        let a = N::new(&arena, "hello").unwrap();
        let b = N::new(&arena, "world").unwrap();
        
        // This also adds another item "c" to the same arena, which
        // will be dropped after the "a" is dropped.
        // This is useful for ensuring the drop order.
        let c = a.outlives("c").unwrap();
        
        // Fixed size array example, initialized 
        // from exact size iterator:
        let a = Array::new(&arena, (0..2).into_iter()).unwrap();
        assert_eq!(a.len(), Some(2));
        
        // The unsafe C-way to initialize array is also available:
        let mut uninitialized_array = Array::<i32>::with_capacity(&arena, 2).unwrap();
        
        unsafe { *(uninitialized_array.data_mut().offset(0)) = 1 }
        unsafe { *(uninitialized_array.data_mut().offset(1)) = 2 }
        
        let a = unsafe { uninitialized_array.initialized_to_len(2) };
        assert_eq!(a.len(), Some(2));
        assert_eq!(a[0], 1);
        assert_eq!(a[1], 2);               

        // The drop functions are executed when the Arena goes out of scope,
        // and the created objects are aware of that because they keep
        // WeakArena inside.
        
        // The memory blocks are returned back to Memory when
        // all WeakArena holders go out of scope.
    }
}

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.