PhantomData

When working with unsafe code, we can often end up in a situation wheretypes or lifetimes are logically associated with a struct, but not actuallypart of a field. This most commonly occurs with lifetimes. For instance, theIter 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 andtypes are forbidden in struct definitions. Therefore we must somehow referto these types in the body. Correctly doing this is necessary to havecorrect variance and drop checking.

We do this using PhantomData, which is a special marker type. PhantomDataconsumes no space, but simulates a field of the given type for the purpose ofstatic analysis. This was deemed to be less error-prone than explicitly tellingthe type-system the kind of variance that you want, while also providing otheruseful things such as the information needed by drop check.

Iter logically contains a bunch of &'a Ts, so this is exactly what we tellthe 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 variantover 'a and T. Everything Just Works.

Another important example is Vec, which is (approximately) defined as follows:

struct Vec<T> {
    data: *const T, // *const for variance!
    len: usize,
    cap: usize,
}

Unlike the previous example, it appears that everything is exactly as wewant. Every generic argument to Vec shows up in at least one field.Good to go!

Nope.

The drop checker will generously determine that Vec<T> does not own any valuesof type T. This will in turn make it conclude that it doesn’t need to worryabout Vec dropping any T’s in its destructor for determining drop checksoundness. This will in turn allow people to create unsoundness usingVec’s destructor.

In order to tell dropck that we do own values of type T, and therefore maydrop some T’s when we drop, we must add an extra PhantomData saying exactlythat:

use std::marker;
struct Vec<T> {
    data: *const T, // *const for variance!
    len: usize,
    cap: usize,
    _marker: marker::PhantomData<T>,
}

Raw pointers that own an allocation is such a pervasive pattern that thestandard library made a utility for itself called Unique<T> which:

• wraps a *const T for variance
• includes a PhantomData<T>
• auto-derives Send/Sync as if T was contained
• marks the pointer as NonZero for the null-pointer optimization

Table of PhantomData patterns

Here’s a table of all the wonderful ways PhantomData could be used:

(*) If contravariance gets scrapped, this would be invariant.