Struct std::marker::PhantomData

pub struct PhantomData<T> where T: ?Sized;

PhantomData<T> allows you to describe that a type acts as if it stores a value of type T, even though it does not. This allows you to inform the compiler about certain safety properties of your code.

For a more in-depth explanation of how to use PhantomData<T>, please see the Nomicon.

A ghastly note 👻👻👻

Though they both have scary names, PhantomData<T> and 'phantom types' are related, but not identical. Phantom types are a more general concept that don't require PhantomData<T> to implement, but PhantomData<T> is the most common way to implement them in a correct manner.

Examples

Unused lifetime parameter

Perhaps the most common time that PhantomData is required is with a struct that has an unused lifetime parameter, typically as part of some unsafe code. For example, here is a struct Slice that has two pointers of type *const T, presumably pointing into an array somewhere:

fn main() { struct Slice<'a, T> { start: *const T, end: *const T, } }

struct Slice<'a, T> {
    start: *const T,
    end: *const T,
}

The intention is that the underlying data is only valid for the lifetime 'a, so Slice should not outlive 'a. However, this intent is not expressed in the code, since there are no uses of the lifetime 'a and hence it is not clear what data it applies to. We can correct this by telling the compiler to act as if the Slice struct contained a borrowed reference &'a T:

fn main() { use std::marker::PhantomData; #[allow(dead_code)] struct Slice<'a, T: 'a> { start: *const T, end: *const T, phantom: PhantomData<&'a T> } }

use std::marker::PhantomData;

struct Slice<'a, T: 'a> {
    start: *const T,
    end: *const T,
    phantom: PhantomData<&'a T>
}

This also in turn requires that we annotate T:'a, indicating that T is a type that can be borrowed for the lifetime 'a.

Unused type parameters

It sometimes happens that there are unused type parameters that indicate what type of data a struct is "tied" to, even though that data is not actually found in the struct itself. Here is an example where this arises when handling external resources over a foreign function interface. PhantomData<T> can prevent mismatches by enforcing types in the method implementations:

fn main() { #![allow(dead_code)] trait ResType { fn foo(&self); } struct ParamType; mod foreign_lib { pub fn new(_: usize) -> *mut () { 42 as *mut () } pub fn do_stuff(_: *mut (), _: usize) {} } fn convert_params(_: ParamType) -> usize { 42 } use std::marker::PhantomData; use std::mem; struct ExternalResource<R> { resource_handle: *mut (), resource_type: PhantomData<R>, } impl<R: ResType> ExternalResource<R> { fn new() -> ExternalResource<R> { let size_of_res = mem::size_of::<R>(); ExternalResource { resource_handle: foreign_lib::new(size_of_res), resource_type: PhantomData, } } fn do_stuff(&self, param: ParamType) { let foreign_params = convert_params(param); foreign_lib::do_stuff(self.resource_handle, foreign_params); } } }

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

struct ExternalResource<R> {
   resource_handle: *mut (),
   resource_type: PhantomData<R>,
}

impl<R: ResType> ExternalResource<R> {
    fn new() -> ExternalResource<R> {
        let size_of_res = mem::size_of::<R>();
        ExternalResource {
            resource_handle: foreign_lib::new(size_of_res),
            resource_type: PhantomData,
        }
    }

    fn do_stuff(&self, param: ParamType) {
        let foreign_params = convert_params(param);
        foreign_lib::do_stuff(self.resource_handle, foreign_params);
    }
}

Indicating ownership

Adding a field of type PhantomData<T> also indicates that your struct owns data of type T. This in turn implies that when your struct is dropped, it may in turn drop one or more instances of the type T, though that may not be apparent from the other structure of the type itself. This is commonly necessary if the structure is using a raw pointer like *mut T whose referent may be dropped when the type is dropped, as a *mut T is otherwise not treated as owned.

If your struct does not in fact own the data of type T, it is better to use a reference type, like PhantomData<&'a T> (ideally) or PhantomData<*const T> (if no lifetime applies), so as not to indicate ownership.

Trait Implementations

impl<T> Hash for PhantomData<T> where T: ?Sized

fn hash<H>(&self, &mut H) where H: Hasher

Feeds this value into the state given, updating the hasher as necessary.

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher

Feeds a slice of this type into the state provided.

impl<T> PartialEq<PhantomData<T>> for PhantomData<T> where T: ?Sized

fn eq(&self, _other: &PhantomData<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> Eq for PhantomData<T> where T: ?Sized

impl<T> PartialOrd<PhantomData<T>> for PhantomData<T> where T: ?Sized

fn partial_cmp(&self, _other: &PhantomData<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Ord for PhantomData<T> where T: ?Sized

fn cmp(&self, _other: &PhantomData<T>) -> Ordering

This method returns an Ordering between self and other.

impl<T> Copy for PhantomData<T> where T: ?Sized

impl<T> Clone for PhantomData<T> where T: ?Sized

fn clone(&self) -> PhantomData<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Default for PhantomData<T> where T: ?Sized

fn default() -> PhantomData<T>

Returns the "default value" for a type.

impl<T> Debug for PhantomData<T> where T: ?Sized

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.