Uniqueness and Aliasing

Chapter 1 — What Uniqueness Means (and How to Encode It)

Uniqueness means: at a given time, no other live reference (&T or &mut T) aliases the same memory location in a way that violates Rust’s rules. We explore how to encode uniqueness guarantees using PhantomData, lifetimes, and careful API shapes.

Chapter 1 — What Uniqueness Means (and How to Encode It)

Uniqueness means: at a given time, no other live reference (&T or &mut T) aliases the same memory location in a way that violates Rust’s rules. We explore how to encode uniqueness guarantees using PhantomData, lifetimes, and careful API shapes.

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}

title: “Unique Pointers in Rust: Encoding Non-Null + No-Alias” meta_description: “Deep-dive on uniqueness and aliasing in Rust: design patterns for containers, provenance, guards, FFI transfers, and tests.” keywords: [“rust unique”, “noalias rust”, “provenance rust”, “nonnull unique”, “vec internals rust”, “panic safety rust”, “miri aliasing”]

Extended Deep Dive

  • Formal invariants for exclusive access and how they relate to &mut guarantees.
  • Lifetimes as capability tokens: when a borrow exists, unique methods are disabled.
  • Using PhantomData to influence variance and auto traits, encoding that your type is invariant over T when necessary.
  • Building UniqueBuf<T>: API surfaces that never hand out aliases concurrently.
  • Recovery from panics with scope guards; proof sketches that len/cap invariants remain true.

Reference Snippets

use std::{ptr::NonNull, marker::PhantomData};

pub struct UniqueBuf<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
    _uniq: PhantomData<&'static mut T>, // encodes "unique" at type level
}