Designing Type-Safe Resource Handles

Wrap raw indices or pointers into distinct, safe handles using markers.

In this lesson, you will learn how to prevent logic bugs by wrapping raw resource IDs in distinct, type-safe structures using PhantomData markers.

The Problem with Raw Handles

In many systems, you might manage different types of resources—like Users, Documents, or Connections—using raw integers (e.g., u32) as IDs. This is dangerous because the compiler sees them all as identical. You could accidentally pass a UserId into a function expecting a DocumentId, and the compiler would stay silent, letting you ship a bug that leads to data corruption.

Using Marker Types for Safety

To fix this, we create "handles." Instead of passing a raw u32 around, we define a struct that acts as a wrapper. To keep our code efficient—without adding memory overhead—we use std::marker::PhantomData. This tells the compiler that our struct is "associated" with a specific type, even though that type doesn't occupy any space at runtime.

use std::marker::PhantomData;

// A generic handle struct
struct Handle<T> {
    id: u32,
    _marker: PhantomData<T>,
}

// Distinct types for our resources
struct User;
struct Document;

fn delete_user(id: Handle<User>) { /* ... */ }

fn main() {
    let user_id = Handle::<User> { id: 1, _marker: PhantomData };
    let doc_id = Handle::<Document> { id: 1, _marker: PhantomData };

    delete_user(user_id); // Works perfectly
    // delete_user(doc_id); // Compile Error: Expected Handle<User>, found Handle<Document>
}

Why this works

By wrapping the ID, we move the responsibility of identity verification from the runtime to the compiler. The PhantomData ensures that Handle<User> and Handle<Document> are treated as two completely different types. If you try to pass the wrong handle into a function, the compiler stops you immediately. This design turns potential runtime crashes into harmless build-time errors, making your resource management much more robust as your system grows.

Key Takeaway: By wrapping raw indices in structs paired with PhantomData, you create compile-time boundaries that prevent type-mismatch bugs without incurring any runtime performance costs.