Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Smart Pointers and Memory

Rust PhantomData<T> type

Reference for Rust PhantomData<T>: zero-sized marker for unused type or lifetime parameters, variance, drop check, Send/Sync control and type-state units.

PhantomData<T> is a zero-sized type that tells the compiler "this struct behaves as if it owned or referred to a T", even though no T is stored. Rust rejects struct definitions with an unused type or lifetime parameter, and PhantomData is the standard way to use the parameter.

It costs nothing at run time (size 0, no code) and it influences three compile-time properties of the surrounding type: variance, drop checking and auto traits (Send/Sync). It is also the engine of the "type-state" and "units of measure" patterns, where a parameter only exists to distinguish types.

Rust
use std::marker::PhantomData;

struct Id<T> {
    raw: u32,
    _kind: PhantomData<T>,
}

Try it

Rust Typed ids that cannot be mixed up

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Lifetime marker and zero size

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
pub struct PhantomData<T: ?Sized>;   // unit-like, constructed as PhantomData

Create a value by writing PhantomData (the type is inferred from the field) or PhantomData::<T>.

Marker you write The struct is treated as...
PhantomData<T> owning a T: covariant in T, drop check assumes T may be dropped, Send/Sync follow T.
PhantomData<&'a T> holding a shared borrow: covariant in 'a and T.
PhantomData<&'a mut T> holding an exclusive borrow: invariant in T.
PhantomData<fn() -> T> producing a T without owning it: covariant, and always Send + Sync.
PhantomData<fn(T)> consuming a T: contravariant in T.
PhantomData<*const T> not Send or Sync, covariant.
PhantomData<Cell<T>> invariant in T, not Sync.

Edge cases. PhantomData<T> always implements Clone, Copy, Default, PartialEq, Hash and the rest, whatever T is. A #[derive(Clone)] on a struct containing it still demands T: Clone on the struct's own impl, which is why the example writes the impls by hand.

Usage notes

  • Type-state: Door<Open> and Door<Closed> share one definition with a PhantomData<State> field, so methods exist only in the right state. See Type state and builders.
  • Raw-pointer containers (Vec, LinkedList, your own arena) hold *mut T or NonNull<T> and add PhantomData<T> so the compiler knows they own T for variance and drop check.
  • Use PhantomData<fn() -> T> when the struct merely tags a type and must stay Send + Sync regardless of T.
  • It has no runtime cost and is not stored in layout; size_of::<PhantomData<T>>() is always 0.
  • A common error message is parameter T is never used; add the field instead of a dummy value.