pub struct RawArena<T> { /* private fields */ }
Expand description
A very-unsafe
, arena for raw pointers that falls back to raw allocation when full. This
should be used with great care, and ideally you should only be using the higher-level arenas
built on top of this.
§Safety
Items placed into the RawArena are dropped, but there is no check to ensure that an allocated
item is valid before dropping it. Use recycle_without_drop
to return an item to the arena
without dropping it.
§Example
// Create a RawArena with a capacity of 10 elements
let arena = RawArena::<usize>::with_capacity(10);
// Allocate elements in the arena
unsafe {
let mut elements = Vec::new();
for i in 0..10 {
let mut element_ptr = arena.allocate();
*element_ptr.as_mut() = i * 2;
elements.push(element_ptr);
}
// Recycle elements back into the arena
for &element_ptr in elements.iter() {
arena.recycle(element_ptr);
}
}
Implementations§
source§impl<T> RawArena<T>
impl<T> RawArena<T>
sourcepub const fn overhead() -> usize
pub const fn overhead() -> usize
Returns the constant overhead per allocation to assist with making allocations page-aligned.
sourcepub const fn allocation_size() -> usize
pub const fn allocation_size() -> usize
Returns the size of each allocation.
sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Allocate an arena, completely initialized. This memory is not zeroed, and we use the high-water mark to keep track of what we’ve initialized so far.
This is safe, because dropping the RawArena
without doing anything to
it is safe.
sourcepub unsafe fn allocate(&self) -> NonNull<T>
pub unsafe fn allocate(&self) -> NonNull<T>
Gets the next free entry, allocating if necessary. This is O(1)
if we have free space in
the arena, O(?)
if we need to allocate from the allocator (where ?
is defined by the
system allocator).
§Safety
As the memory area is considered uninitialized and you must be careful to fully and validly initialize the underlying data, this method is marked as unsafe.
This pointer will be invalidated when we drop the RawArena
, so the allocator API is unsafe
as there are no lifetimes here.
IMPORTANT: Ensure all allocated entries are fully initialized before dropping RawArena
,
or use recycle_without_drop
to manually handle recycling, as dropping the arena does not
perform any validation or cleanup on the allocated items. Dropping RawArena
will automatically
trigger the drop of all items allocated within.
sourcepub unsafe fn allocate_if_space(&self) -> Option<NonNull<T>>
pub unsafe fn allocate_if_space(&self) -> Option<NonNull<T>>
Gets the next free entry, returning null if full. This is O(1)
.
§Safety
As the memory area is considered uninitialized and you must be careful to fully and validly initialize the underlying data, this method is marked as unsafe.
This pointer will be invalidated when we drop the RawArena
, so the allocator API is unsafe
as there are no lifetimes here.
IMPORTANT: Ensure all allocated entries are fully initialized before dropping RawArena
,
or use recycle_without_drop
to manually handle recycling, as dropping the arena does not
perform any validation or cleanup on the allocated items. Dropping RawArena
will automatically
trigger the drop of all items allocated within.
sourcepub fn remaining(&self) -> usize
pub fn remaining(&self) -> usize
Returns the remaining capacity of this RawArena
that can be provided without allocation.
sourcepub fn allocated(&self) -> usize
pub fn allocated(&self) -> usize
Returns the remaining capacity of this RawArena
that can be provided without allocation.
sourcepub unsafe fn clear_allocated(&self)
pub unsafe fn clear_allocated(&self)
Clear all internally-allocated entries, resetting the arena state to its original state. Any non-vacant entries are dropped.
This operation must walk the vacant list and is worst-case O(n)
, where n
is the largest
size of this arena since the last clear operation.
§Safety
Does not clear system-allocator entries. Pointers previously allocate
d may still be in use.
sourcepub unsafe fn recycle(&self, data: NonNull<T>) -> bool
pub unsafe fn recycle(&self, data: NonNull<T>) -> bool
Recycle a used item, returning it to the next-free list. Drops the associated item in place before recycling.
§Safety
We assume this pointer is either internal to the arena (in which case we return it
to the arena), or allocated via std::alloc::alloc
in allocate
.
sourcepub unsafe fn recycle_without_drop(&self, data: NonNull<T>) -> bool
pub unsafe fn recycle_without_drop(&self, data: NonNull<T>) -> bool
Recycle a used item, returning it to the next-free list.
§Safety
We assume this pointer is either internal to the arena (in which case we return it
to the arena), or allocated via std::alloc::alloc
in allocate
.