Struct shared_arena::SharedArena

pub struct SharedArena<T: Sized> { /* fields omitted */ }

An arena shareable across threads

Pointers to the elements in the SharedArena are shareable as well.

Example

use shared_arena::SharedArena;
use std::sync::Arc;

let arena = Arc::new(SharedArena::new());
let arena2 = arena.clone();

let value = std::thread::spawn(move || {
    arena2.alloc(100)
});

let item = arena.alloc(1);

assert_eq!(*item + *value.join().unwrap(), 101);

std::mem::drop(arena);

// The value is still valid, even if the arena has been dropped
assert_eq!(*item, 1);

Implementations

impl<T: Sized> SharedArena<T>

pub fn with_capacity(cap: usize) -> SharedArena<T>

Constructs a new SharedArena capable of holding at least cap elements

Because the arena allocate by page of 63 elements, it might be able to hold more elements than cap.

The Arena will reallocate itself if there is not enough space when allocating (with alloc* functions)

Example

let arena = SharedArena::with_capacity(2048);

pub fn new() -> SharedArena<T>

Constructs a new SharedArena capable of holding exactly 63 elements

The Arena will reallocate itself if there is not enough space when allocating (with alloc* functions)

Example

let arena = SharedArena::new();

pub fn alloc(&self, value: T) -> ArenaBox<T>

Writes a value in the arena, and returns an ArenaBox pointing to that value.

Example

let arena = SharedArena::new();
let my_num: ArenaBox<u8> = arena.alloc(0xFF);

assert_eq!(*my_num, 255);

pub fn alloc_with<F>(&self, initializer: F) -> ArenaBox<T> where
    F: Fn(&mut MaybeUninit<T>) -> &T, 

Finds an empty space in the arena and calls the function initializer with its argument pointing to that space. It returns an ArenaBox pointing to the newly initialized value.

The difference with alloc is that it has the benefit of avoiding intermediate copies of the value.

Safety

It is the caller responsability to initialize properly the value.
initializer must return &T, this is a way to ensure that its parameter &mut MaybeUninit<T> has been "consumed".

If initializer returns a different reference than its parameter, the function will panic.

When the ArenaBox is dropped, the value is also dropped. If the value is not initialized correctly, it will drop an unitialized value, which is undefined behavior.

Example

struct MyData {
    a: usize
}

fn initialize_data<'a>(uninit: &'a mut MaybeUninit<MyData>, source: &MyData) -> &'a MyData {
    unsafe {
        let ptr = uninit.as_mut_ptr();
        ptr::copy(source, ptr, 1);
        &*ptr
    }
}

let arena = SharedArena::<MyData>::new();
let source = MyData { a: 101 };

let data = arena.alloc_with(|uninit| {
    initialize_data(uninit, &source)
});
assert!(data.a == 101);

pub fn alloc_arc(&self, value: T) -> ArenaArc<T>

Writes a value in the arena, and returns an ArenaArc pointing to that value.

Example

let arena = SharedArena::new();
let my_num: ArenaArc<u8> = arena.alloc_arc(0xFF);

assert_eq!(*my_num, 255);

pub fn alloc_arc_with<F>(&self, initializer: F) -> ArenaArc<T> where
    F: Fn(&mut MaybeUninit<T>) -> &T, 

Finds an empty space in the arena and calls the function initializer with its argument pointing to that space. It returns an ArenaArc pointing to the newly initialized value.

The difference with alloc_arc is that it has the benefit of avoiding intermediate copies of the value.

Safety

It is the caller responsability to initialize properly the value.
initializer must return &T, this is a way to ensure that its parameter &mut MaybeUninit<T> has been "consumed".

If initializer returns a different reference than its parameter, the function will panic.

When all ArenaArc pointing that value are dropped, the value is also dropped. If the value is not initialized correctly, it will drop an unitialized value, which is undefined behavior.

Example

struct MyData {
    a: usize
}

fn initialize_data<'a>(uninit: &'a mut MaybeUninit<MyData>, source: &MyData) -> &'a MyData {
    unsafe {
        let ptr = uninit.as_mut_ptr();
        ptr::copy(source, ptr, 1);
        &*ptr
    }
}

let arena = SharedArena::<MyData>::new();
let source = MyData { a: 101 };

let data = arena.alloc_arc_with(|uninit| {
    initialize_data(uninit, &source)
});
assert!(data.a == 101);

pub fn alloc_rc(&self, value: T) -> ArenaRc<T>

Writes a value in the arena, and returns an ArenaRc pointing to that value.

Example

let arena = SharedArena::new();
let my_num: ArenaRc<u8> = arena.alloc_rc(0xFF);

assert_eq!(*my_num, 255);

pub fn alloc_rc_with<F>(&self, initializer: F) -> ArenaRc<T> where
    F: Fn(&mut MaybeUninit<T>) -> &T, 

Finds an empty space in the arena and calls the function initializer with its argument pointing to that space. It returns an ArenaRc pointing to the newly initialized value.

The difference with alloc_rc is that it has the benefit of avoiding intermediate copies of the value.

Safety

It is the caller responsability to initialize properly the value.
initializer must return &T, this is a way to ensure that its parameter &mut MaybeUninit<T> has been "consumed".

If initializer returns a different reference than its parameter, the function will panic.

When all ArenaRc pointing that value are dropped, the value is also dropped. If the value is not initialized correctly, it will drop an unitialized value, which is undefined behavior.

Example

struct MyData {
    a: usize
}

fn initialize_data<'a>(uninit: &'a mut MaybeUninit<MyData>, source: &MyData) -> &'a MyData {
    unsafe {
        let ptr = uninit.as_mut_ptr();
        ptr::copy(source, ptr, 1);
        &*ptr
    }
}

let arena = SharedArena::<MyData>::new();
let source = MyData { a: 101 };

let data = arena.alloc_rc_with(|uninit| {
    initialize_data(uninit, &source)
});
assert!(data.a == 101);

pub fn shrink_to_fit(&self) -> bool

Shrinks the capacity of the arena as much as possible.

It will drop all pages that are unused (no Arena{Box,Arc,Rc} points to it).
If there is still one or more references to a page, the page won't be dropped.

This is a slow function and it should not be called in a hot path.

The dedicated memory will be deallocated in an undetermined time in the future, not during the function call. While the time is not determined, it's guarantee that it will be deallocated.
shrink_to_fit on Arena and Pool don't have this behavior.

Note that if SharedArena becomes full and one of the alloc_* function is called, it might reuses the pages freed by this function, if it has not be deallocated yet.

Example

let mut arena = SharedArena::with_capacity(2048);
let mut values = Vec::new();

let (used, free) = arena.stats();
assert!(used == 0, free == 2048);

for _ in 0..80 {
    values.push(arena.alloc(0xFF));
}

arena.shrink_to_fit();

let (used, free) = arena.stats();
assert!(used == 80, free == 46);

pub fn stats(&self) -> (usize, usize)

Returns a tuple of non-free and free spaces in the arena

This is a slow function and it should not be called in a hot path.

Example

let arena = SharedArena::new();
let item = arena.alloc(1);
let (used, free) = arena.stats();
assert!(used == 1 && free == 62);

Trait Implementations

impl<T> Debug for SharedArena<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Sized> Default for SharedArena<T>

fn default() -> SharedArena<T>

Returns the "default value" for a type.

impl<T> Drop for SharedArena<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Sized> Send for SharedArena<T>

impl<T: Sized> Sync for SharedArena<T>