Reinventing From Scratch — Box<T>

Chapter 1 — A Mental Model of `Box<T>`

1.1 What `Box<T>` is

A single-owner, single-allocation smart pointer. On the stack: one word (a pointer). On the heap: exactly one initialized T.

Stack                    Heap
+---------+              0x7ff3... → [   T bytes   ]
|  ptr ---+-------------------------------▶
+---------+

1.2 Guarantees

Unique ownership: moving the box transfers ownership; clones aren’t implicit.
Exactly-once drop: the pointee is dropped once when the box goes out of scope.
Stable address of T: moving Box<T> moves the handle, not the pointee.

🧠 Why it matters: Stable addresses enable FFI handles and graph structures where pointers between nodes must remain valid.

1.3 Typical uses

Large structs to avoid stack blowups.
Trait objects and DSTs (via std Box, discussed later).
Owning heap state with deterministic destruction.

1.4 Non‑goals

Capacity management (that’s Vec<T>).
Shared ownership (that’s Rc<T>/Arc<T>).

Sidenote — “Smart” means “has rules”

Box<T> is simple because its invariants are crisp: one pointer, one value, one drop. Everything else—coercions, pinning—is gravy on top of those rules.

Exercises

Explain why Box<T> gives a stable address even when moved.
When is Box<T> not the right tool? Give two examples.

Deep Dive: Ownership Proofs, Drop Order, and DST Considerations

A. Formal Invariants for `MyBox<T>` (Sized)

B1 (Pointer Validity): ptr is either null only after into_raw or a valid, properly aligned pointer to initialized T.
B2 (Single Drop): The destructor of T is invoked exactly once if and only if ptr is non-null at Drop time.
B3 (Dealloc after Drop): dealloc(layout_of::<T>()) is called exactly once, and only after drop_in_place.
B4 (From/Into Raw Consistency): from_raw only accepts pointers produced by into_raw of the same type/allocator; mixing allocators is UB.
B5 (No References to Uninit): No &/&mut references are created before ptr::write initializes the allocation.

B.1 Single Drop — Drop checks for null and calls drop_in_place once; into_raw nulls out ptr and forgets self, preventing Drop from running on a live value.
B.2 No Use-After-Free — Deallocation happens only after the destructor; references returned by Deref are derived from a live ptr and never stored beyond the box’s lifetime.
B.3 Panic Safety — If constructor panics before publishing, no ownership is established; if Drop panics (should not), process aborts, avoiding double-unwind corruption.

C. DST Box Notes

Slices (Box<[T]>): store length; the fat pointer (data, len) enables correct deallocation.
Box<str>: same as [u8] with UTF‑8 invariant; length in metadata.
Box<dyn Trait>: fat pointer (data, vtable); the vtable encodes drop and size/alignment; std uses compiler magic for correct layout.

D. Interop Patterns

FFI Ownership Transfer: into_raw -> C takes ownership; C must call back into Rust with from_raw or a custom free.
Leaking Globals: leak returns 'static reference, acceptable for process lifetime singletons; document intent.

E. Debugging

Double Drop: look for *p assignment instead of ptr::write on uninitialized memory.
Mismatched Layout: using dealloc with wrong Layout causes heap corruption; keep Layout::new::<T>() paired.

F. Exercises

Implement try_new returning Result<MyBox<T>, AllocError>.
Add into_inner(self) -> T by ptr::read and skipping dealloc? Explain why you must still dealloc after moving T.
Implement MyVec::into_boxed_slice that hands RawVec buffer to a Box<[T]> safely.

FAQ (Extended)

Q: Does Box<T> guarantee a stable address? A: Yes, the pointee’s address is stable for the life of the box; moving the box moves only the handle.
Q: Why ptr::write not *p = value? A: The latter reads/drops the previous contents (uninitialized), which is UB.
Q: Can Box<T> be null? A: By design, standard Box<T> is non-null; our MyBox may set ptr = null only as a consumed sentinel post-into_raw.
Q: Is Pin<Box<T>> needed for stable address? A: Not for stability; Pin is for forbidding moves via the API.

Mental Model and Ownership