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.
use std::marker::PhantomData; struct Id<T> { raw: u32, _kind: PhantomData<T>, }
Try it
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.
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
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>andDoor<Closed>share one definition with aPhantomData<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 TorNonNull<T>and addPhantomData<T>so the compiler knows they ownTfor variance and drop check. - Use
PhantomData<fn() -> T>when the struct merely tags a type and must staySend + Syncregardless ofT. - 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.