From 9f555d7c7facf00277904f0e9dedf2970fd55c22 Mon Sep 17 00:00:00 2001 From: overlookmotel <557937+overlookmotel@users.noreply.github.com> Date: Wed, 16 Oct 2024 15:35:53 +0000 Subject: [PATCH] docs(allocator): clarify docs for `Box` (#6625) Clarify the consequences of storing `Drop` types in `oxc_allocator::Box`. --- crates/oxc_allocator/src/boxed.rs | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/crates/oxc_allocator/src/boxed.rs b/crates/oxc_allocator/src/boxed.rs index 46f5a753376e3..4e74ba9df6e5f 100644 --- a/crates/oxc_allocator/src/boxed.rs +++ b/crates/oxc_allocator/src/boxed.rs @@ -16,10 +16,16 @@ use serde::{Serialize, Serializer}; use crate::Allocator; -/// A Box without [`Drop`]. +/// A `Box` without [`Drop`], which stores its data in the arena allocator. /// -/// This is used for over coming self-referential structs. -/// It is a memory leak if the boxed value has a [`Drop`] implementation. +/// Should only be used for storing AST types. +/// +/// Must NOT be used to store types which have a [`Drop`] implementation. +/// `T::drop` will NOT be called on the `Box`'s contents when the `Box` is dropped. +/// If `T` owns memory outside of the arena, this will be a memory leak. +/// +/// Note: This is not a soundness issue, as Rust does not support relying on `drop` +/// being called to guarantee soundness. pub struct Box<'alloc, T: ?Sized>(NonNull, PhantomData<(&'alloc (), T)>); impl<'alloc, T> Box<'alloc, T> {