|
|
# 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:
|
|
|
|
|
|
```rust,ignore
|
|
|
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][dropck-eyepatch] for details. This can be ignored if you
|
|
|
don't know what the eyepatch is.
|
|
|
|
|
|
Iter logically contains a bunch of `&'a T`s, 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 | - |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[dropck-eyepatch]: dropck-eyepatch.html
|
