Struct rarena_allocator::Arena

pub struct Arena { /* private fields */ }

Arena should be lock-free

Implementations

impl Arena

pub const fn version(&self) -> u16

Returns the version of the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let version = arena.version();

pub const fn magic_version(&self) -> u16

Returns the magic version of the ARENA. This value can be used to check the compatibility for application using Arena.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let magic_version = arena.magic_version();

pub fn allocated(&self) -> usize

Returns the number of bytes allocated by the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let allocated = arena.allocated();

pub const fn capacity(&self) -> usize

Returns the capacity of the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let capacity = arena.capacity();

pub fn remaining(&self) -> usize

Returns the number of bytes remaining bytes can be allocated by the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let remaining = arena.remaining();

pub fn refs(&self) -> usize

Returns the number of references to the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let refs = arena.refs();

pub fn discarded(&self) -> u32

Returns the number of bytes discarded by the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let discarded = arena.discarded();

pub fn increase_discarded(&self, size: u32)

Forcelly increases the discarded bytes.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
arena.increase_discarded(100);

pub fn minimum_segment_size(&self) -> u32

Returns the minimum segment size of the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let min_segment_size = arena.minimum_segment_size();

pub fn set_minimum_segment_size(&self, size: u32)

Sets the minimum segment size of the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
arena.set_minimum_segment_size(100);

pub const fn data_offset(&self) -> usize

Returns the data offset of the ARENA. The offset is the end of the reserved bytes of the ARENA.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let data_offset = arena.data_offset();

pub fn data(&self) -> &[u8]

Returns the data section of the ARENA as a byte slice, header is not included.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let data = arena.data();

pub const fn memory(&self) -> &[u8]

Returns the whole main memory of the ARENA as a byte slice.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let memory = arena.memory();

pub const fn read_only(&self) -> bool

Returns true if the arena is read-only.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());
let read_only = arena.read_only();

impl Arena

pub fn new(opts: ArenaOptions) -> Self

Creates a new ARENA with the given options.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());

pub fn map_mut<P: AsRef<Path>>( path: P, opts: ArenaOptions, open_options: OpenOptions, mmap_options: MmapOptions, ) -> Result<Self>

Creates a new ARENA backed by a mmap with the given options.

Example

use rarena_allocator::{Arena, ArenaOptions, OpenOptions, MmapOptions};


let open_options = OpenOptions::default().create_new(Some(100)).read(true).write(true);
let mmap_options = MmapOptions::new();
let arena = Arena::map_mut(&path, ArenaOptions::new(), open_options, mmap_options).unwrap();

pub fn map<P: AsRef<Path>>( path: P, open_options: OpenOptions, mmap_options: MmapOptions, magic_version: u16, ) -> Result<Self>

Opens a read only ARENA backed by a mmap with the given capacity.

Example

use rarena_allocator::{Arena, ArenaOptions, OpenOptions, MmapOptions};



let open_options = OpenOptions::default().read(true);
let mmap_options = MmapOptions::new();
let arena = Arena::map(&path, open_options, mmap_options, 0).unwrap();

pub fn map_anon(opts: ArenaOptions, mmap_options: MmapOptions) -> Result<Self>

Creates a new ARENA backed by an anonymous mmap with the given capacity.

Example

use rarena_allocator::{Arena, ArenaOptions, MmapOptions};

let mmap_options = MmapOptions::new().len(100);
let arena = Arena::map_anon(ArenaOptions::new(), mmap_options).unwrap();

pub fn flush(&self) -> Result<()>

Flushes the memory-mapped file to disk.

Example

use rarena_allocator::{Arena, ArenaOptions, OpenOptions, MmapOptions};

let open_options = OpenOptions::default().create_new(Some(100)).read(true).write(true);
let mmap_options = MmapOptions::new();
let mut arena = Arena::map_mut(&path, ArenaOptions::new(), open_options, mmap_options).unwrap();
arena.flush().unwrap();

pub fn flush_async(&self) -> Result<()>

Flushes the memory-mapped file to disk asynchronously.

Example

use rarena_allocator::{Arena, ArenaOptions, OpenOptions, MmapOptions};

let open_options = OpenOptions::default().create(Some(100)).read(true).write(true);
let mmap_options = MmapOptions::new();
let mut arena = Arena::map_mut(&path, ArenaOptions::new(), open_options, mmap_options).unwrap();

arena.flush_async().unwrap();

pub fn alloc_bytes_owned(&self, size: u32) -> Result<BytesMut, Error>

Allocates an owned slice of memory in the ARENA.

The cost of this method is an extra atomic operation, compared to alloc_bytes.

pub fn alloc_bytes(&self, size: u32) -> Result<BytesRefMut<'_>, Error>

Allocates a slice of memory in the ARENA.

The BytesRefMut is zeroed out.

If you want a BytesMut, see alloc_bytes_owned.

pub fn alloc_aligned_bytes_owned<T>(&self, size: u32) -> Result<BytesMut, Error>

Allocates an owned byte slice that can hold a well-aligned T and extra size bytes.

The layout of the allocated memory is:

| T | [u8; size] |

Example

let mut bytes = arena.alloc_aligned_bytes_owned::<T>(extra).unwrap();
bytes.put(val).unwrap(); // write `T` to the byte slice.

pub fn alloc_aligned_bytes<T>( &self, size: u32, ) -> Result<BytesRefMut<'_>, Error>

Allocates a byte slice that can hold a well-aligned T and extra size bytes.

The layout of the allocated memory is:

| T | [u8; size] |

Example

let mut bytes = arena.alloc_aligned_bytes::<T>(extra).unwrap();
bytes.put(val).unwrap(); // write `T` to the byte slice.

pub unsafe fn alloc<T>(&self) -> Result<RefMut<'_, T>, Error>

Allocates a T in the ARENA.

Safety

• If T needs to be dropped and callers invoke RefMut::detach, then the caller must ensure that the T is dropped before the ARENA is dropped. Otherwise, it will lead to memory leaks.

• If this is file backed ARENA, then T must be recoverable from bytes.

  1. Types require allocation are not recoverable.
  2. Pointers are not recoverable, like *const T, *mut T, NonNull and any structs contains pointers, although those types are on stack, but they cannot be recovered, when reopens the file.

Examples

Memory leak

The following example demonstrates the memory leak when the T is a heap allocated type and detached.

let arena = Arena::new(ArenaOptions::new());

{
  let mut data = arena.alloc::<Vec<u8>>().unwrap();
  data.detach();
  data.write(vec![1, 2, 3]);
}

drop(arena); // memory leak, the `Vec<u8>` is not dropped.

Undefined behavior

The following example demonstrates the undefined behavior when the T is not recoverable.

struct TypeOnHeap {
  data: Vec<u8>,
}

let arena = Arena::map_mut("path/to/file", ArenaOptions::new(), OpenOptions::create_new(Some(1000)).read(true).write(true), MmapOptions::default()).unwrap();

let mut data = arena.alloc::<TypeOnHeap>().unwrap();
data.detach();
data.write(TypeOnHeap { data: vec![1, 2, 3] });
let offset = data.offset();
drop(arena);

// reopen the file
let arena = Arena::map("path/to/file", OpenOptions::read(true), MmapOptions::default()).unwrap();

let foo = &*arena.get_aligned_pointer::<TypeOnHeap>(offset as usize);
let b = foo.data[1]; // undefined behavior, the `data`'s pointer stored in the file is not valid anymore.

Good practice

Some examples about how to use this method correctly.

Heap allocated type with carefull memory management

let arena = Arena::new(ArenaOptions::new());

// Do not invoke detach, so when the data is dropped, the drop logic will be handled by the ARENA.
// automatically.
{
  let mut data = arena.alloc::<Vec<u8>>().unwrap();
  data.write(vec![1, 2, 3]);
}


let mut detached_data = arena.alloc::<Vec<u8>>().unwrap();
detached_data.detach();
detached_data.write(vec![4, 5, 6]);

// some other logic

core::ptr::drop_in_place(detached_data.as_mut()); // drop the `Vec` manually.

drop(arena); // it is safe, the `Vec` is already dropped.

Recoverable type with file backed ARENA

struct Recoverable {
  field1: u64,
  field2: AtomicU32,
}

let arena = Arena::map_mut("path/to/file", ArenaOptions::new(), OpenOptions::create_new(Some(1000)).read(true).write(true), MmapOptions::default()).unwrap();

let mut data = arena.alloc::<Recoverable>().unwrap();
data.write(Recoverable { field1: 10, field2: AtomicU32::new(20) });
data.detach();
let offset = data.offset();
drop(arena);

// reopen the file
let arena = Arena::map("path/to/file", OpenOptions::read(true), MmapOptions::default()).unwrap();

let foo = &*arena.get_aligned_pointer::<Recoverable>(offset as usize);

assert_eq!(foo.field1, 10);
assert_eq!(foo.field2.load(Ordering::Acquire), 20);

pub unsafe fn alloc_owned<T>(&self) -> Result<Owned<T>, Error>

Allocates a T in the ARENA. Like alloc, but returns an Owned.

The cost is one more atomic operation than alloc.

Safety

• See alloc for safety.

Example

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());

unsafe {
  let mut data = arena.alloc_owned::<u64>().unwrap();
  data.write(10);

  assert_eq!(*data.as_ref(), 10);
}

pub unsafe fn clear(&self) -> Result<(), Error>

Clear the ARENA.

Safety

• The current pointers get from the ARENA cannot be used anymore after calling this method.
• This method is not thread-safe.

Examples

Undefine behavior:

let mut data = arena.alloc::<Vec<u8>>().unwrap();

arena.clear();

data.write(vec![1, 2, 3]); // undefined behavior

Good practice:

use rarena_allocator::{Arena, ArenaOptions};

let arena = Arena::new(ArenaOptions::new());

unsafe {
  let mut data = arena.alloc::<Vec<u8>>().unwrap();
  data.write(vec![1, 2, 3]);

  arena.clear().unwrap();
}

pub unsafe fn dealloc(&self, offset: u32, size: u32) -> bool

Deallocates the memory at the given offset and size, the offset..offset + size will be made to a segment, returns true if the deallocation is successful.

Safety

• you must ensure the same offset..offset + size is not deallocated twice.
• offset must be larger than the Arena::data_offset.
• offset + size must be less than the Arena::allocated.

pub const unsafe fn get_bytes(&self, offset: usize, size: usize) -> &[u8]

Returns a bytes slice from the ARENA.

Safety

• offset..offset + size must be allocated memory.
• offset must be less than the capacity of the ARENA.
• size must be less than the capacity of the ARENA.
• offset + size must be less than the capacity of the ARENA.

pub unsafe fn get_bytes_mut(&self, offset: usize, size: usize) -> &mut [u8]

Returns a mutable bytes slice from the ARENA. If the ARENA is read-only, then this method will return an empty slice.

Safety

• offset..offset + size must be allocated memory.
• offset must be less than the capacity of the ARENA.
• size must be less than the capacity of the ARENA.
• offset + size must be less than the capacity of the ARENA.

Panic

• If the ARENA is read-only, then this method will panic.

pub const unsafe fn get_pointer(&self, offset: usize) -> *const u8

Returns a pointer to the memory at the given offset.

Safety

• offset must be less than the capacity of the ARENA.

pub unsafe fn get_pointer_mut(&self, offset: usize) -> *mut u8

Returns a pointer to the memory at the given offset. If the ARENA is read-only, then this method will return a null pointer.

Safety

• offset must be less than the capacity of the ARENA.

Panic

• If the ARENA is read-only, then this method will panic.

pub unsafe fn get_aligned_pointer<T>(&self, offset: usize) -> *const T

Returns an aligned pointer to the memory at the given offset.

Safety

• offset..offset + mem::size_of::<T>() + padding must be allocated memory.
• offset must be less than the capacity of the ARENA.

pub unsafe fn get_aligned_pointer_mut<T>(&self, offset: usize) -> NonNull<T>

Returns an aligned pointer to the memory at the given offset. If the ARENA is read-only, then this method will return a null pointer.

Safety

• offset..offset + mem::size_of::<T>() + padding must be allocated memory.
• offset must be less than the capacity of the ARENA.

Panic

• If the ARENA is read-only, then this method will panic.

pub unsafe fn offset(&self, ptr: *const u8) -> usize

Returns the offset to the start of the ARENA.

Safety

• ptr must be allocated by this ARENA.

Trait Implementations

impl Clone for Arena

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Arena

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

Formats the value using the given formatter.

impl Drop for Arena

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Arena

impl Sync for Arena