Preface: Why Start with Box<T>?

Reinventing From Scratch — Box<T>

Chapter 0 — Preface: Why Start with Box<T>?

A hands-on, unsafe tour of Rust’s simplest owning pointer.

What this book is (and isn’t)

This book is a from-the-metal reconstruction of Box<T>. We’ll hold raw pointers, call the allocator, and enforce invariants ourselves. The goal is understanding, not replacing the standard library.

What you’ll build

  • A minimal yet fully functional MyBox<T> for sized types.
  • Ownership transfer APIs: into_raw, from_raw, leak.
  • Correct Drop ordering: drop_in_place → dealloc.
  • Ergonomics (Deref, DerefMut) and mental models (stable addresses).
  • Extensions: NonNull, ZSTs, niche optimization, a gentle look at Pin, DST boxes ([T], str, dyn Trait).

Reading style

Rustonomicon-flavored: sidenotes, warnings, ascii diagrams, and end-of-chapter exercises and checklists.

⚠️ Unsafe ahead. Expect std::alloc, raw pointers, and places where a single off‑by‑one means UB.

Pre-requisites

  • Comfortable with ownership/borrowing.
  • Basic generics and traits.
  • Some fear, a healthy respect for unsafe, and Miri installed.

Exercises

  1. Summarize how Box<T> differs from Vec<T> in one paragraph.
  2. Name three reasons one might choose Box<T> over a stack value.

Checklist

  • I accept that this is for learning and I won’t ship MyBox<T> in prod.
  • I can run cargo +nightly miri test.

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. Proof Sketches

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

  1. Implement try_new returning Result<MyBox<T>, AllocError>.
  2. Add into_inner(self) -> T by ptr::read and skipping dealloc? Explain why you must still dealloc after moving T.
  3. 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.