nomicon/src/phantom-data.md

PhantomData

When working with unsafe code, we can often end up in a situation where types or lifetimes are logically associated with a struct, but not actually part of a field. This most commonly occurs with lifetimes. For instance, the Iter for &'a [T] is (approximately) defined as follows:

struct Iter<'a, T: 'a> {
    ptr: *const T,
    end: *const T,
}

However because 'a is unused within the struct's body, it's unbounded. Because of the troubles this has historically caused, unbounded lifetimes and types are forbidden in struct definitions. Therefore we must somehow refer to these types in the body. Correctly doing this is necessary to have correct variance and drop checking.

We do this using PhantomData, which is a special marker type. PhantomData consumes no space, but simulates a field of the given type for the purpose of static analysis. This was deemed to be less error-prone than explicitly telling the type system the kind of variance that you want, while also being useful for secondary concerns like deriving Send and Sync.

When using the drop check eyepatch, PhantomData also becomes important for telling the compiler about all types that you drop that it can't see. See the the previous section for details. This can be ignored if you don't know what the eyepatch is.

Iter logically contains a bunch of &'a Ts, so this is exactly what we tell the PhantomData to simulate:

use std::marker;

struct Iter<'a, T: 'a> {
    ptr: *const T,
    end: *const T,
    _marker: marker::PhantomData<&'a T>,
}

and that's it. The lifetime will be bounded, and your iterator will be variant over 'a and T. Everything Just Works.

Here's a more extreme example based on HashMap which stores a single opaque allocation which is used for multiple arrays of different types:

use std::marker;

struct HashMap<K, V> {
    ptr: *mut u8,
    // The pointer actually stores keys and values
    // (and hashes, but those aren't generic)
    _marker: marker::PhantomData<(K, V)>,
}

Table of PhantomData patterns

Here’s a table of all the most common ways PhantomData is used:

Phantom type	'a	T
PhantomData<T>	-	variant (and drop check T)
PhantomData<&'a T>	variant	variant
PhantomData<&'a mut T>	variant	invariant
PhantomData<*const T>	-	variant
PhantomData<*mut T>	-	invariant
PhantomData<fn(T)>	-	contravariant
PhantomData<fn() -> T>	-	variant
PhantomData<fn(T) -> T>	-	invariant
PhantomData<Cell<&'a ()>>	invariant	-