Ffi

You write a generic struct, never actually store a T in any field, and the compiler stops you with “parameter T is never used”. PhantomData<T> is the zero-cost lie that fixes it — a marker that occupies no bytes but tells the compiler “act as if I own a T.”

The problem shows up the moment you build a typed handle around something that isn’t a T:

1
2
3
4

// Won't compile: T isn't actually stored anywhere.
struct TypedId<T> {
    raw: u64,
}

rustc rejects this because an unused type parameter is almost always a bug — variance, drop checking, and Send/Sync all depend on what a struct claims to own. std::marker::PhantomData<T> is the escape hatch: a zero-sized struct that pretends the type parameter is used:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use std::marker::PhantomData;

struct TypedId<T> {
    raw: u64,
    _marker: PhantomData<T>,
}

impl<T> TypedId<T> {
    fn new(raw: u64) -> Self {
        Self { raw, _marker: PhantomData }
    }
}

struct User;
struct Order;

let u: TypedId<User>  = TypedId::new(1);
let o: TypedId<Order> = TypedId::new(1);

// Same raw value, different types — the compiler refuses to mix them.
// let _: TypedId<User> = o; // error: expected TypedId<User>, found TypedId<Order>

assert_eq!(std::mem::size_of::<TypedId<User>>(), 8); // still just the u64

The _marker field disappears at runtime — size_of::<TypedId<User>>() is exactly size_of::<u64>(). But at compile time, TypedId<User> and TypedId<Order> are distinct types you can’t accidentally swap.

The same pattern fixes lifetimes too. FFI wrappers borrow from a buffer they don’t physically point into:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::marker::PhantomData;

struct CursorHandle<'a> {
    raw_ptr: *const u8,
    _borrow: PhantomData<&'a [u8]>,
}

impl<'a> CursorHandle<'a> {
    fn new(buf: &'a [u8]) -> Self {
        Self { raw_ptr: buf.as_ptr(), _borrow: PhantomData }
    }
}

let buf = vec![1u8, 2, 3];
let cursor = CursorHandle::new(&buf);
// drop(buf); // compile error — cursor still borrows it, thanks to PhantomData
let _ = cursor;

Without the PhantomData<&'a [u8]>, the 'a would be unused and the compiler wouldn’t enforce that buf outlives cursor. With it, the borrow checker treats CursorHandle<'a> as if it held a real &'a [u8].

Three flavors of PhantomData you’ll see in the wild — pick by what you want the compiler to believe:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::marker::PhantomData;

// 1. Owns a T (covariant, drops a T): PhantomData<T>
struct Owns<T>(PhantomData<T>);

// 2. Borrows a T (no drop): PhantomData<&'a T>
struct Borrows<'a, T>(PhantomData<&'a T>);

// 3. Neither Send nor Sync: PhantomData<*const ()>
struct NotThreadSafe(PhantomData<*const ()>);

fn assert_send<T: Send>() {}
// assert_send::<NotThreadSafe>(); // would fail — raw ptr makes it !Send

assert_eq!(std::mem::size_of::<Owns<u64>>(), 0);
assert_eq!(std::mem::size_of::<Borrows<'_, u64>>(), 0);
assert_eq!(std::mem::size_of::<NotThreadSafe>(), 0);

That last one is the cheap way to opt a type out of Send/Sync without unsafe — Rc<T> uses exactly this trick internally to stay single-threaded.

PhantomData is the bookkeeping behind almost every wrapper type you’ve used. Cell, Cow, Pin, Rc, and NonNull all carry one — it’s how they tell the compiler what they conceptually own without paying for it at runtime.

You reserve 4 KiB to read from a socket, and to hand the buffer over you first… write 4096 zeros. Vec::spare_capacity_mut exposes the reserved-but-uninitialized tail as &mut [MaybeUninit<u8>] so the callback writes straight into the allocation.

The pain: paying to overwrite

The intuitive fill-a-buffer pattern resizes the Vec first so the slice exists:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

let mut buf: Vec<u8> = Vec::with_capacity(8);
buf.resize(8, 0); // writes 8 zeros we're about to clobber

// Pretend this is `read(fd, buf.as_mut_ptr(), buf.len())`.
fill(&mut buf);

assert_eq!(buf, b"rustbite");

fn fill(out: &mut [u8]) {
    out.copy_from_slice(b"rustbite");
}

It works, but resize walks the whole tail writing zeros that the next line overwrites — a measurable cost for big reads, and pointless for types where “zero” isn’t even a valid value.

The fix: write into the uninitialized tail

Vec::spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>] hands you a slice covering exactly capacity - len slots. Write into them, then call set_len to tell the Vec they’re now initialized:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::mem::MaybeUninit;

let mut buf: Vec<u8> = Vec::with_capacity(8);

// View the reserved-but-uninitialized tail.
let spare: &mut [MaybeUninit<u8>] = buf.spare_capacity_mut();
assert_eq!(spare.len(), 8);

// Write through the MaybeUninit pointer — no zeroing first.
for (slot, byte) in spare.iter_mut().zip(b"rustbite") {
    slot.write(*byte);
}

// Promise the Vec those 8 slots are now valid `u8`s.
unsafe { buf.set_len(8); }

assert_eq!(buf, b"rustbite");

spare_capacity_mut itself is safe — MaybeUninit<T> is the type that lets you hold “maybe garbage” without UB. The unsafe block is just the set_len call where you assert you really did initialize them.

Pairing with a real fill API

The standard pattern is “reserve, write, set_len”:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

use std::mem::MaybeUninit;

fn read_bytes(buf: &mut Vec<u8>, extra: usize, source: &[u8]) {
    buf.reserve(extra);

    let spare = buf.spare_capacity_mut();
    let n = extra.min(source.len()).min(spare.len());

    // Initialize the prefix we actually wrote.
    for i in 0..n {
        spare[i].write(source[i]);
    }

    // Only extend by what's been initialized.
    unsafe { buf.set_len(buf.len() + n); }
}

let mut v = vec![b'>', b' '];
read_bytes(&mut v, 8, b"rustbite");
assert_eq!(v, b"> rustbite");

The same shape works with read-style callbacks: cast the MaybeUninit<u8> slice to a raw pointer, hand it to C, and only extend len by the byte count the call returned. The bytes you didn’t write stay MaybeUninit — never read them.

When to reach for it

Reading from sockets, files, or FFI fill-style APIs into a Vec<u8> is the headline use case — every tokio and mio read path eventually bottoms out in this pattern. It’s also useful for non-Copy types where there’s no sensible default to seed with: image decoders writing Vec<Pixel>, audio decoders writing Vec<f32>, parser arenas writing Vec<Node>.

If you don’t need the spare capacity view — you’re building up element-by-element — Vec::push (or Vec::push_mut from bite 88) is still the right call. spare_capacity_mut is the tool for the moment you have an external writer that wants a flat buffer and you’d rather not pay to zero it first.

You want to give a Rust-allocated buffer to C and re-take it later. That means handing over (ptr, len, capacity) — and historically, prying those three out of a Vec without freeing the allocation meant wrapping the vector in ManuallyDrop first. Rust 1.93 stabilises Vec::into_raw_parts, a single safe call that returns the triple and consumes the Vec for you.

The pain: extracting parts while suppressing drop

The classic recipe leaks the Vec’s destructor on purpose so the C side owns the memory. You need three reads and a guard to keep Drop from racing the allocator:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

use std::mem::ManuallyDrop;

let v: Vec<u32> = vec![10, 20, 30];

let mut me = ManuallyDrop::new(v);
let ptr = me.as_mut_ptr();
let len = me.len();
let cap = me.capacity();

assert_eq!(unsafe { *ptr.add(1) }, 20);
assert_eq!((len, cap), (3, 3));

// Hand (ptr, len, cap) to C here.
// Reclaim it later with Vec::from_raw_parts to free the allocation.
let _reclaimed = unsafe { Vec::from_raw_parts(ptr, len, cap) };

It works, but the ManuallyDrop wrapper exists only to keep the destructor from running. Forget it, write mem::forget(v) in the wrong order, or read capacity() after the move and you’ve got a use-after-free or a leak.

The fix: one safe call, three return values

Vec::into_raw_parts(self) -> (*mut T, usize, usize) consumes the Vec, hands you the pointer-length-capacity triple, and leaves the allocation alive for you to manage:

1
2
3
4
5
6
7
8
9

let v: Vec<u32> = vec![10, 20, 30];
let (ptr, len, cap) = v.into_raw_parts();

assert_eq!((len, cap), (3, 3));
assert_eq!(unsafe { *ptr.add(1) }, 20);

// Reclaim and free at the end (or hand to C and have C call back).
let reclaimed = unsafe { Vec::from_raw_parts(ptr, len, cap) };
assert_eq!(reclaimed, vec![10, 20, 30]);

No wrapper, no separate field reads, no chance of accidentally calling a &self method after the move. The method is const, too.

String::into_raw_parts follows the same shape

String gets the same treatment in 1.93. The triple is (*mut u8, usize, usize), which is what String::from_raw_parts wants back:

1
2
3
4
5
6
7

let s = String::from("hello");
let (ptr, len, cap) = s.into_raw_parts();

assert_eq!((len, cap), (5, 5));

let rebuilt = unsafe { String::from_raw_parts(ptr, len, cap) };
assert_eq!(rebuilt, "hello");

The pairing is the point: into_raw_parts is safe (the Vec/String is gone, no aliasing exists yet), and from_raw_parts is unsafe (you’re asserting the triple came from a matching allocator with the right layout). The split keeps the unsafety where it actually lives.

When to reach for it

Any FFI boundary where the C side will hold the buffer for a while: graphics buffers, codec frames, command queues, anything with an extern "C" fn free_my_thing(ptr, len, cap) callback. Also handy when you’re building your own typed handles around a raw allocation — Box::into_raw covers the single-value case; into_raw_parts covers the variable-length one.

If you only need the pointer and nothing will ever reclaim the allocation, Vec::leak is still the shorter call. Reach for into_raw_parts the moment the capacity matters — i.e. anyone, anywhere, might want to give the memory back.

You need the byte offset of a field — for FFI, custom serialization, or talking to a C struct. The old answer was unsafe pointer arithmetic on a MaybeUninit, or pulling in the memoffset crate. std::mem::offset_of! is the safe, one-liner replacement.

The problem

Say you’re matching a C layout and need to know exactly where each field lives in memory:

1
2
3
4
5
6
7

#[repr(C)]
struct Header {
    magic: u32,
    version: u16,
    flags: u16,
    payload_len: u64,
}

The pre-1.77 way meant either an external crate or hand-rolled unsafe:

1
2
3
4
5
6
7
8

use std::mem::MaybeUninit;

fn payload_len_offset_old() -> usize {
    let uninit = MaybeUninit::<Header>::uninit();
    let base = uninit.as_ptr() as usize;
    let field = unsafe { &raw const (*uninit.as_ptr()).payload_len } as usize;
    field - base
}

It works, but unsafe, raw pointers, and a MaybeUninit is a lot of ceremony for “where does this field start?”

The fix: mem::offset_of!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use std::mem::offset_of;

let magic_off       = offset_of!(Header, magic);
let version_off     = offset_of!(Header, version);
let flags_off       = offset_of!(Header, flags);
let payload_len_off = offset_of!(Header, payload_len);

assert_eq!(magic_off, 0);
assert_eq!(version_off, 4);
assert_eq!(flags_off, 6);
assert_eq!(payload_len_off, 8);

No unsafe. No allocation. No instance of Header ever exists. The macro expands to a const-evaluable usize — usable inside const fn and static items.

Nested fields work too

Dot through a path of named fields and offset_of! keeps walking:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

#[repr(C)]
struct Inner {
    a: u32,
    b: u32,
}

#[repr(C)]
struct Outer {
    tag: u8,
    _pad: [u8; 3],
    inner: Inner,
}

assert_eq!(offset_of!(Outer, inner), 4);
assert_eq!(offset_of!(Outer, inner.b), 8);

Tuples and tuple structs use numeric indices:

1
2
3
4
5

#[repr(C)]
struct Pair(u8, u32);

assert_eq!(offset_of!(Pair, 0), 0);
assert_eq!(offset_of!(Pair, 1), 4);

When it earns its keep

FFI bindings, custom binary parsers, kernel-style intrusive data structures, and anywhere you’d otherwise reach for memoffset. The macro is in core, so it works in no_std. Reach for it whenever you find yourself writing as *const _ as usize math.