Struct AllocatorGuard

pub struct AllocatorGuard<'alloc_pool> { /* private fields */ }

A guard object representing exclusive access to an Allocator from the pool.

On drop, the Allocator is reset and returned to the pool.

Methods from Deref<Target = Allocator>

pub fn alloc<T>(&self, val: T) -> &mut T

Allocate an object in this Allocator and return an exclusive reference to it.

Panics

Panics if reserving space for T fails.

Examples

use oxc_allocator::Allocator;

let allocator = Allocator::default();
let x = allocator.alloc([1u8; 20]);
assert_eq!(x, &[1u8; 20]);

pub fn alloc_str<'alloc>(&'alloc self, src: &str) -> &'alloc str

Copy a string slice into this Allocator and return a reference to it.

Panics

Panics if reserving space for the string fails.

Examples

use oxc_allocator::Allocator;
let allocator = Allocator::default();
let hello = allocator.alloc_str("hello world");
assert_eq!(hello, "hello world");

pub fn alloc_slice_copy<T: Copy>(&self, src: &[T]) -> &mut [T]

Copy a slice into this Bump and return an exclusive reference to the copy.

Panics

Panics if reserving space for the slice fails.

Examples

use oxc_allocator::Allocator;
let allocator = Allocator::default();
let x = allocator.alloc_slice_copy(&[1, 2, 3]);
assert_eq!(x, &[1, 2, 3]);

pub fn alloc_layout(&self, layout: Layout) -> NonNull<u8>

Allocate space for an object with the given Layout.

The returned pointer points at uninitialized memory, and should be initialized with std::ptr::write.

Panics

Panics if reserving space matching layout fails.

pub fn alloc_concat_strs_array<'a, const N: usize>( &'a self, strings: [&str; N], ) -> &'a str

Create new &str from a fixed-size array of &strs concatenated together, allocated in the given allocator.

Panics

Panics if the sum of length of all strings exceeds isize::MAX.

Example

use oxc_allocator::Allocator;

let allocator = Allocator::new();
let s = allocator.alloc_concat_strs_array(["hello", " ", "world", "!"]);
assert_eq!(s, "hello world!");

pub fn capacity(&self) -> usize

Calculate the total capacity of this Allocator including all chunks, in bytes.

Note: This is the total amount of memory the Allocator owns NOT the total size of data that’s been allocated in it. If you want the latter, use used_bytes instead.

Examples

use oxc_allocator::Allocator;

let capacity = 64 * 1024; // 64 KiB
let mut allocator = Allocator::with_capacity(capacity);
allocator.alloc(123u64); // 8 bytes

// Result is the capacity (64 KiB), not the size of allocated data (8 bytes).
// `Allocator::with_capacity` may allocate a bit more than requested.
assert!(allocator.capacity() >= capacity);

pub fn used_bytes(&self) -> usize

Calculate the total size of data used in this Allocator, in bytes.

This is the total amount of memory that has been used in the Allocator, NOT the amount of memory the Allocator owns. If you want the latter, use capacity instead.

The result includes:

1. Padding bytes between objects which have been allocated to preserve alignment of types where they have different alignments or have larger-than-typical alignment.
2. Excess capacity in Vecs, StringBuilders and HashMaps.
3. Objects which were allocated but later dropped. Allocator does not re-use allocations, so anything which is allocated into arena continues to take up “dead space”, even after it’s no longer referenced anywhere.
4. “Dead space” left over where a Vec, StringBuilder or HashMap has grown and had to make a new allocation to accommodate its new larger size. Its old allocation continues to take up “dead” space in the allocator, unless it was the most recent allocation.

In practice, this almost always means that the result returned from this function will be an over-estimate vs the amount of “live” data in the arena.

However, if you are using the result of this method to create a new Allocator to clone an AST into, it is theoretically possible (though very unlikely) that it may be a slight under-estimate of the capacity required in new allocator to clone the AST into, depending on the order that &strs were allocated into arena in parser vs the order they get allocated during cloning. The order allocations are made in affects the amount of padding bytes required.

Examples

use oxc_allocator::{Allocator, Vec};

let capacity = 64 * 1024; // 64 KiB
let mut allocator = Allocator::with_capacity(capacity);

allocator.alloc(1u8); // 1 byte with alignment 1
allocator.alloc(2u8); // 1 byte with alignment 1
allocator.alloc(3u64); // 8 bytes with alignment 8

// Only 10 bytes were allocated, but 16 bytes were used, in order to align `3u64` on 8
assert_eq!(allocator.used_bytes(), 16);

allocator.reset();

let mut vec = Vec::<u64>::with_capacity_in(2, &allocator);

// Allocate something else, so `vec`'s allocation is not the most recent
allocator.alloc(123u64);

// `vec` has to grow beyond it's initial capacity
vec.extend([1, 2, 3, 4]);

// `vec` takes up 32 bytes, and `123u64` takes up 8 bytes = 40 total.
// But there's an additional 16 bytes consumed for `vec`'s original capacity of 2,
// which is still using up space
assert_eq!(allocator.used_bytes(), 56);

Trait Implementations

impl Deref for AllocatorGuard<'_>

type Target = Allocator

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for AllocatorGuard<'_>

fn drop(&mut self)

Return Allocator back to the pool.