Generics

#165 May 2026

165. PhantomData<T> — The Zero-Sized Marker That Pretends to Own a T

You write a generic struct, never actually store a T in any field, and the compiler stops you with “parameter T is never used”. PhantomData<T> is the zero-cost lie that fixes it — a marker that occupies no bytes but tells the compiler “act as if I own a T.”

The problem shows up the moment you build a typed handle around something that isn’t a T:

1
2
3
4
// Won't compile: T isn't actually stored anywhere.
struct TypedId<T> {
    raw: u64,
}

rustc rejects this because an unused type parameter is almost always a bug — variance, drop checking, and Send/Sync all depend on what a struct claims to own. std::marker::PhantomData<T> is the escape hatch: a zero-sized struct that pretends the type parameter is used:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
use std::marker::PhantomData;

struct TypedId<T> {
    raw: u64,
    _marker: PhantomData<T>,
}

impl<T> TypedId<T> {
    fn new(raw: u64) -> Self {
        Self { raw, _marker: PhantomData }
    }
}

struct User;
struct Order;

let u: TypedId<User>  = TypedId::new(1);
let o: TypedId<Order> = TypedId::new(1);

// Same raw value, different types — the compiler refuses to mix them.
// let _: TypedId<User> = o; // error: expected TypedId<User>, found TypedId<Order>

assert_eq!(std::mem::size_of::<TypedId<User>>(), 8); // still just the u64

The _marker field disappears at runtime — size_of::<TypedId<User>>() is exactly size_of::<u64>(). But at compile time, TypedId<User> and TypedId<Order> are distinct types you can’t accidentally swap.

The same pattern fixes lifetimes too. FFI wrappers borrow from a buffer they don’t physically point into:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
use std::marker::PhantomData;

struct CursorHandle<'a> {
    raw_ptr: *const u8,
    _borrow: PhantomData<&'a [u8]>,
}

impl<'a> CursorHandle<'a> {
    fn new(buf: &'a [u8]) -> Self {
        Self { raw_ptr: buf.as_ptr(), _borrow: PhantomData }
    }
}

let buf = vec![1u8, 2, 3];
let cursor = CursorHandle::new(&buf);
// drop(buf); // compile error — cursor still borrows it, thanks to PhantomData
let _ = cursor;

Without the PhantomData<&'a [u8]>, the 'a would be unused and the compiler wouldn’t enforce that buf outlives cursor. With it, the borrow checker treats CursorHandle<'a> as if it held a real &'a [u8].

Three flavors of PhantomData you’ll see in the wild — pick by what you want the compiler to believe:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
use std::marker::PhantomData;

// 1. Owns a T (covariant, drops a T): PhantomData<T>
struct Owns<T>(PhantomData<T>);

// 2. Borrows a T (no drop): PhantomData<&'a T>
struct Borrows<'a, T>(PhantomData<&'a T>);

// 3. Neither Send nor Sync: PhantomData<*const ()>
struct NotThreadSafe(PhantomData<*const ()>);

fn assert_send<T: Send>() {}
// assert_send::<NotThreadSafe>(); // would fail — raw ptr makes it !Send

assert_eq!(std::mem::size_of::<Owns<u64>>(), 0);
assert_eq!(std::mem::size_of::<Borrows<'_, u64>>(), 0);
assert_eq!(std::mem::size_of::<NotThreadSafe>(), 0);

That last one is the cheap way to opt a type out of Send/Sync without unsafe — Rc<T> uses exactly this trick internally to stay single-threaded.

PhantomData is the bookkeeping behind almost every wrapper type you’ve used. Cell, Cow, Pin, Rc, and NonNull all carry one — it’s how they tell the compiler what they conceptually own without paying for it at runtime.