Struct Box 

pub struct Box<'alloc, T>(/* private fields */)
where
    T: ?Sized;

A Box without Drop, which stores its data in the arena allocator.

No Drops

Objects allocated into Oxc memory arenas are never Dropped. Memory is released in bulk when the allocator is dropped, without dropping the individual objects in the arena.

Therefore, it would produce a memory leak if you allocated Drop types into the arena which own memory allocations outside the arena.

Static checks make this impossible to do. Box::new_in will refuse to compile if called with a Drop type.

Implementations

impl<'alloc, T> Box<'alloc, T>

pub fn new_in(value: T, allocator: &impl GetAllocator<'alloc>) -> Box<'alloc, T>

Allocate value into the memory arena, and receive a Box which owns the value.

Examples

use oxc_allocator::{Allocator, Box};

let arena = Allocator::default();
let arena = &arena;
let in_arena: Box<i32> = Box::new_in(5, &arena);

The Box cannot outlive the Allocator. This fails to compile:

use oxc_allocator::{Allocator, Box};

let boxed = {
    let allocator = Allocator::default();
    let allocator = &allocator;
    Box::new_in(5, &allocator)
};
assert_eq!(*boxed, 5);

pub fn unbox(self) -> T

Take ownership of the value stored in this Box, consuming the box in the process.

Examples

use oxc_allocator::{Allocator, Box};

let arena = Allocator::default();
let arena = &arena;

// Put `5` into the arena and on the heap.
let boxed: Box<i32> = Box::new_in(5, &arena);
// Move it back to the stack. `boxed` has been consumed.
let i = boxed.unbox();

assert_eq!(i, 5);

impl<T> Box<'_, T>

where T: ?Sized,

pub fn as_non_null(boxed: &Box<'_, T>) -> NonNull<T>

Get a NonNull pointer pointing to the Box’s contents.

The pointer is not valid for writes.

The caller must ensure that the Box outlives the pointer this function returns, or else it will end up dangling.

Example

use oxc_allocator::{Allocator, Box};

let allocator = Allocator::new();
let allocator = &allocator;
let boxed = Box::new_in(123_u64, &allocator);
let ptr = Box::as_non_null(&boxed);

pub fn into_non_null(boxed: Box<'_, T>) -> NonNull<T>

Consume a Box and return a NonNull pointer to its contents.

pub const unsafe fn from_non_null(ptr: NonNull<T>) -> Box<'_, T>

Create a Box from a NonNull pointer.

SAFETY

• Pointer must point to a valid T.
• Pointer must point to within an Allocator.
• Caller must ensure that the pointer is valid for the lifetime of the Box.

impl<T> Box<'static, [T]>

pub fn new_empty_boxed_slice() -> Box<'static, [T]>

Create a new empty Box<[T]>.

This method does not allocate. The returned boxed slice is represented by a dangling, correctly-aligned pointer with length 0, similar to how Vec::new_in produces an empty vector.

impl<'alloc, T> Box<'alloc, [T]>

pub fn into_arena_slice(self) -> &'alloc [T]

Convert a boxed slice [Box<[T]>] into slice [&'alloc [T]].

The returned slice has the same lifetime as the allocator.

pub fn into_arena_slice_mut(self) -> &'alloc mut [T]

Convert a boxed slice [Box<[T]>] into mutable slice [&'alloc mut [T]].

The returned slice has the same lifetime as the allocator.

Trait Implementations

impl<T> AsMut<T> for Box<'_, T>

where T: ?Sized,

fn as_mut(&mut self) -> &mut T

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsRef<T> for Box<'_, T>

where T: ?Sized,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<'new_alloc, T, C> CloneIn<'new_alloc> for Box<'_, T>

where T: CloneIn<'new_alloc, Cloned = C>,

type Cloned = Box<'new_alloc, C>

The type of the cloned object.

fn clone_in_impl( &self, with_semantic_ids: CloneInSemanticIds, allocator: &'new_alloc Allocator, ) -> <Box<'_, T> as CloneIn<'new_alloc>>::Cloned

Clone self into allocator, threading whether semantic ids should be preserved as a runtime with_semantic_ids flag rather than as two separate methods.

fn clone_in(&self, allocator: &'new_alloc Allocator) -> Self::Cloned

Clone self into the given allocator. allocator may be the same one that self is already in.

fn clone_in_with_semantic_ids( &self, allocator: &'new_alloc Allocator, ) -> Self::Cloned

Almost identical as clone_in, but for some special type, it will also clone the semantic ids. Please use this method only if you make sure semantic info is synced with the ast node.

impl<'new_alloc, T, C> CloneIn<'new_alloc> for Box<'_, [T]>

where T: CloneIn<'new_alloc, Cloned = C>,

type Cloned = Box<'new_alloc, [C]>

The type of the cloned object.

fn clone_in_impl( &self, with_semantic_ids: CloneInSemanticIds, allocator: &'new_alloc Allocator, ) -> <Box<'_, [T]> as CloneIn<'new_alloc>>::Cloned

Clone self into allocator, threading whether semantic ids should be preserved as a runtime with_semantic_ids flag rather than as two separate methods.

fn clone_in(&self, allocator: &'new_alloc Allocator) -> Self::Cloned

Clone self into the given allocator. allocator may be the same one that self is already in.

fn clone_in_with_semantic_ids( &self, allocator: &'new_alloc Allocator, ) -> Self::Cloned

Almost identical as clone_in, but for some special type, it will also clone the semantic ids. Please use this method only if you make sure semantic info is synced with the ast node.

impl<T> ContentEq for Box<'_, T>

where T: ContentEq,

Blanket implementation for Box types

fn content_eq(&self, other: &Box<'_, T>) -> bool

This method tests for contents of self and other to be equal.

fn content_ne(&self, other: &Self) -> bool

This method tests for contents of self and other not to be equal. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Debug for Box<'_, T>

where T: Debug + ?Sized,

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

Formats the value using the given formatter.

impl<T> Deref for Box<'_, T>

where T: ?Sized,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> DerefMut for Box<'_, T>

where T: ?Sized,

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<T> Display for Box<'_, T>

where T: Display + ?Sized,

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

Formats the value using the given formatter.

impl<'a, T> Dummy<'a> for Box<'a, T>

where T: Dummy<'a>,

fn dummy(allocator: &'a Allocator) -> Box<'a, T>

Create a dummy Box.

impl<'a, T> Dummy<'a> for Box<'a, [T]>

fn dummy(_allocator: &'a Allocator) -> Box<'a, [T]>

Create a dummy empty [Box<[T]>] boxed slice.

impl<T> ESTree for Box<'_, T>

where T: ESTree,

Available on crate feature serialize only.

fn serialize<S>(&self, serializer: S)

where S: Serializer,

impl<'a, T> From<Vec<'a, T>> for Box<'a, [T]>

where T: 'a,

fn from(v: Vec<'a, T>) -> Box<'a, [T]>

Converts to this type from the input type.

impl<'a, T> FromIn<'a, T> for Box<'a, T>

fn from_in(value: T, allocator: &'a Allocator) -> Box<'a, T>

Converts to this type from the input type within the given allocator.

impl<T> GetAddress for Box<'_, T>

fn address(&self) -> Address

Get the memory address of a value allocated in the arena.

AST nodes in a Box in an arena are guaranteed to never move in memory, so this address acts as a unique identifier for the duration of the arena’s existence.

impl<T> Hash for Box<'_, T>

where T: Hash,

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, T> ReplaceWith<'a> for Box<'a, T>

where T: Dummy<'a>,

fn replace_with(&mut self, replacer: impl FnOnce(Self) -> Self)

Replace the node in place with the value returned by replacer.

impl<'a, T> ReplaceWith<'a> for Box<'a, [T]>

fn replace_with(&mut self, replacer: impl FnOnce(Self) -> Self)

Replace the node in place with the value returned by replacer.

impl<T> Send for Box<'_, T>

where T: Send + ?Sized,

SAFETY: A Box has exclusive access to the T it points to, and grants access to nothing else, so it gets the same auto traits as the &'alloc mut T it stands in for.

Unlike Vec, a Box holds no &Arena. There is no way from a Box to the Allocator it points into, so 2 Boxes on different threads cannot both allocate from the same arena - which is the reason Vec cannot be Send. new_in is the only method which touches an Allocator, and it receives one as a param, so it runs on a thread which has one already.

A Box is never Drop, so sending one to another thread cannot free arena memory there. 'alloc borrows the arena, so it cannot be reset or dropped while a Box into it is alive on any thread.

A T which itself holds arena data keeps its own bound - a Box<Vec<T>> is not Send, because Vec is not.

impl<T> Serialize for Box<'_, T>

where T: Serialize,

Available on crate feature serialize only.

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> Sync for Box<'_, T>

where T: Sync + ?Sized,

SAFETY: Sharing a &Box<T> shares only a &T, so T being Sync is what it takes. The Send impl above covers why a Box grants access to nothing else.

impl<'a, T> TakeIn<'a> for Box<'a, [T]>

fn take_in(&mut self, allocator_accessor: &impl GetAllocator<'a>) -> Self

Replace node with a dummy, and return the original.

fn take_in_box( &mut self, allocator_accessor: &impl GetAllocator<'a>, ) -> Box<'a, Self>

Replace node with a dummy, allocate the original node into the arena, and return it as a Box<Self>.