PhantomData: llevar información de tipo sin ocupar memoria

A veces necesitas un parámetro de tipo que no guardas. Un identificador que sea de usuario o de producto según a qué apunte, aunque por dentro sea el mismo u64. Un envoltorio sobre un puntero crudo que posea lógicamente un T sin tener un campo T. Rust, sin embargo, no te deja declarar un parámetro genérico y no usarlo: es un error de compilación. Y aunque te dejara, el compilador necesitaría saber cosas sobre ese T —si lo posees, cómo varía, si es seguro compartirlo entre hilos— que no puede adivinar de la nada. PhantomData<T> resuelve ambos problemas a la vez: es un campo fantasma, de tamaño cero, que le dice al compilador compórtate como si aquí hubiera un T, sin que lo haya.

El parámetro que no aparece

Declara un struct genérico cuyo parámetro no toque ningún campo y el compilador te frena en seco:

struct Marca<T> {
    nombre: String,
}
// error[E0392]: parameter `T` is never used
// help: consider removing `T`, or using a marker such as `PhantomData`

La regla no es un capricho. El compilador deduce propiedades de un tipo genérico —su varianza, qué debe vivir tanto como él, si es Send— a partir de cómo usa cada parámetro en sus campos. Un parámetro que no aparece en ninguno no tiene esas propiedades definidas, y Rust prefiere rechazarlo a inventarlas. La cura es un campo que use T sin ocupar espacio:

use std::marker::PhantomData;

struct Marca<T> {
    nombre: String,
    _tipo: PhantomData<T>,   // usa T; ocupa cero bytes
}

PhantomData<T> es un tipo de tamaño cero: size_of::<PhantomData<T>>() vale 0 para cualquier T. Añadirlo no cambia la disposición de Marca<T> en memoria —sigue pesando lo que una String— pero satisface la regla de uso y, sobre todo, le entrega al compilador la información de tipo que necesita.

use std::marker::PhantomData;
use std::mem::size_of;

struct Marca<T>(String, PhantomData<T>);

fn main() {
    assert_eq!(size_of::<PhantomData<u64>>(), 0);
    assert_eq!(size_of::<Marca<f64>>(), size_of::<String>()); // el marcador no pesa
}

Marcadores con significado

El uso más inmediato es fabricar tipos distintos que comparten representación. Un identificador numérico que no debe confundirse con otro según a qué entidad apunte:

use std::marker::PhantomData;

struct Id<T> {
    valor: u64,
    _tipo: PhantomData<T>,
}

impl<T> Id<T> {
    fn nuevo(valor: u64) -> Id<T> {
        Id { valor, _tipo: PhantomData }
    }
}

struct Usuario;
struct Producto;

fn buscar_usuario(id: Id<Usuario>) { /* ... */ }

fn main() {
    let u: Id<Usuario> = Id::nuevo(1);
    let p: Id<Producto> = Id::nuevo(1);
    buscar_usuario(u);      // OK
    // buscar_usuario(p);   // ERROR: se esperaba Id<Usuario>, no Id<Producto>
}

Id<Usuario> e Id<Producto> son, en memoria, un u64 idéntico; en el sistema de tipos, universos separados. Pasar el identificador de un usuario donde se espera el de un producto no es un fallo que descubras en pruebas: no compila. Y como el marcador no pesa, Id<Usuario> ocupa exactamente lo mismo que un u64. La misma técnica da unidades: un Cantidad<Metros> y un Cantidad<Segundos> sobre un f64 que el compilador se niega a sumar entre sí.

Propiedad, drop check y varianza

PhantomData hace más que rellenar un hueco: le comunica al compilador tres cosas sutiles sobre T.

Propiedad y drop check. Un puntero crudo *const T no implica que poseas el T al que apunta; para el compilador, un struct con solo un *const T no es responsable de ningún T. Si en realidad lo posees —lo construyes y lo liberas, como hace Vec— debes declararlo, o el drop check razonará mal sobre los tiempos de vida:

use std::marker::PhantomData;

struct MiCaja<T> {
    ptr: *const T,               // un puntero crudo NO implica propiedad
    _propiedad: PhantomData<T>,  // le decimos que SI poseemos un T
}

Con PhantomData<T>, el compilador trata MiCaja<T> como si contuviera un T y exige que cualquier referencia dentro de ese T viva tanto como la caja. Sin él podrías liberar antes de tiempo y leer memoria muerta en el Drop.

Varianza. La varianza describe cómo se relacionan Envoltorio<A> y Envoltorio<B> cuando A es subtipo de B —en la práctica, cuando un tiempo de vida dura más que otro—. La forma exacta de PhantomData que elijas fija esa relación:

• PhantomData<T> es covariante en T: lo habitual, un T que dura más encaja donde se espera uno que dura menos.
• PhantomData<fn(T)> es contravariante en T: útil cuando T solo aparece como entrada.
• PhantomData<fn(T) -> T> y PhantomData<*mut T> son invariantes: T debe coincidir exactamente, sin flexibilidad.

La invarianza importa cuando un T mal emparejado abriría un agujero de seguridad; por eso Cell<T> y &mut T son invariantes. PhantomData es la palanca con la que un tipo unsafe reclama la varianza correcta.

Auto-traits. PhantomData<T> es Send si y solo si T lo es, y Sync si y solo si T lo es. Marcar tu tipo con él propaga automáticamente esas garantías de hilos desde T, sin que escribas una línea de más.

flowchart TB
p[Parametro T sin campo que lo use] --> e[Error E0392 parametro nunca usado]
e --> f[PhantomData de T lo reintroduce sin ocupar memoria]
f --> a[Regla de uso satisfecha]
f --> b[Propiedad senalada al drop check]
f --> c[Varianza y auto traits derivados de T]
style f fill:#cba6f7,color:#11111b
style a fill:#a6e3a1,color:#11111b
style b fill:#89b4fa,color:#11111b
style c fill:#f9e2af,color:#11111b