Encapsulating Unsafe with Invariants

Soundness has a one-sentence definition worth memorizing: safe code can never cause undefined behavior. The moment a safe function of yours can be called with arguments that make the unsafe code underneath do something invalid, the whole crate is unsound — and no amount of unsafe at the call site protects you, because callers were told they did not need any.

The shape that keeps the promise is a two-layer split. The safe layer checks every precondition it can check and returns a Result; the unsafe core assumes the checks already happened and contains no branches, no error paths, and no doubt.

pub struct Buf { data: *mut u8, len: usize }

impl Buf {
    /// Copy `bytes` into a buffer the C side will read.
    pub fn from_bytes(bytes: &[u8]) -> Option<Buf> {
        if bytes.is_empty() { return None; }          // reject before any unsafe runs
        // allocation cannot fail here; C requires 16-byte alignment
        if bytes.as_ptr() as usize % 16 != 0 { return None; }

        let data = unsafe { ffi::alloc(bytes.len()) }; // core: one obligation, one line
        if data.is_null() { return None; }

        // SAFETY: data is 16-aligned, len bytes are writable, src is len initialized bytes
        // and the two ranges cannot overlap (fresh allocation vs. caller's slice).
        unsafe { std::ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len()); }
        Some(Buf { data, len: bytes.len() })
    }

    /// # Safety
    /// `f` must tolerate `self.len()` bytes and must not retain the pointer.
    pub unsafe fn read_with(&self, f: unsafe fn(*const u8, usize)) {
        // SAFETY: constructor guarantees data is non-null, aligned, and live for &'a self;
        // the caller contract above covers retention.
        f(self.data, self.len)
    }
}

Every precondition has a home, and the table is the review artifact:

The two "structurally" rows matter most: the strongest invariant is one a caller cannot violate because the type system gives them no way to express it. If Buf is not Clone, holds the only pointer, and frees in Drop, then uniqueness is proven by construction rather than re-checked at every call.

Note the division of labor in read_with: conditions you can verify are verified in the safe path, while the one thing only an outsider can know — that the callback tolerates the buffer — is pushed onto an unsafe fn with a # Safety section. Blurring that line is how sound crates fail: a length check presented as if it also proved initialization, or a safe function that forwards a caller-supplied length straight into slice::from_raw_parts.

Interviewers test this by handing you an API and asking "how would you make it safe?" Answer in two moves: enumerate the preconditions, then name the layer that checks each one. The preconditions themselves are the same six the dereference checklist in Raw Pointers uses — non-null, aligned, initialized, in bounds, live, correctly aliased — which is why that topic is a hard prerequisite here. What you write down next, and how a reviewer verifies it, is the next chapter.

An unsafe block without a written argument is a code review of a memory model. The comment convention exists so the reviewer's job is ordinary: each unsafe block carries a // SAFETY: line stating the invariant and where it comes from, such that a second person can verify it by reading the surrounding code — not by reconstructing your mental state from three months ago.

// BAD — a conclusion the reviewer must take on faith
unsafe { *p = v };

// BAD — restates the operation, adds nothing
// SAFETY: dereferencing raw pointer

// GOOD — each claim checkable at a named location
// SAFETY: p comes from Vec::as_mut_ptr in `new` (line 41); the Vec is borrowed
// exclusively by &mut self, so no other reference to this slot exists; `i` was
// bounds-checked by the caller-facing get_mut above; T = u32 is always initialized.
unsafe { *p = v };

The difference is falsifiability. The good comment names where each of the six conditions is established, and if a reviewer cannot find that location, the code is wrong or the comment is — either way you have found a bug before it shipped. This is the practical meaning of "every unsafe block needs a safety argument": the argument must be local enough to check and specific enough to refute.

Unsafe functions need the same treatment from the other side, because their callers are the ones making promises. Rust API guidelines prescribe a # Safety section on every unsafe fn, one bullet per obligation:

/// Reads a frame from the mapped file.
///
/// # Safety
/// `map` must be a live mapping of at least `offset + len` bytes — file truncation
/// after mapping invalidates this and makes the read undefined behavior.
pub unsafe fn read_frame(map: *const u8, offset: usize, len: usize) -> Vec<u8> { /* ... */ }

A missing # Safety on an unsafe fn is not a style complaint: with no stated contract, there is no such thing as a correct caller, and the function is unusable-sound. Inside the body, #![deny(unsafe_op_in_unsafe_fn)] keeps the obligations from dissolving into an implicitly-unsafe function, and clippy::undocumented_unsafes fails the build when a new unsafe { } appears without its comment — conventions that survive deadlines only when a linter enforces them.

An incomplete comment is a reviewable defect, not a style preference: if an invariant is actually established somewhere else, the reviewer has to go find it — and if they cannot, you have a bug or a lie. Treat a SAFETY comment the way you treat an assertion: it must be possible to imagine the code change that makes it false, and the reviewer should be able to picture that change in a single step.

Two habits separate documentation that ages well from documentation that rots. Put the comment above the block, adjacent to the code it certifies, because a comment three screens away is a comment nobody updates. And treat a stale comment as a defect: the invariant that was true before a refactor and false after it is exactly how aliasing bugs enter a codebase, and it is why reviewers of unsafe code are trained to ask "where is this established?" rather than "is this right?".

That question — who promises what, and how do you enforce the promise — generalizes beyond functions. Some promises are global properties of a type, and Rust has a construct for those: the unsafe trait, covered next, before we close the phase on Common Unsoundness Patterns.

An unsafe fn puts obligations on the caller. An unsafe trait puts obligations on the implementor — a global promise about every value of the type, spanning threads, allocations, and program phases that no single method body can prove.

Send and Sync are the canonical pair, and their definitions are promises about what other code may assume. Interviewers probe them with two questions: which side of the trait is bound by the unsafe marker, and what failure mode follows if the promise is broken. The table is the answer to the second:

The reason raw pointers are !Send and !Sync by default is the compiler refusing to guess: it cannot know whether the address points at thread-local memory or at a buffer another thread is writing. If you do know, you assert it:

struct Handle(*mut ffi::Session);   // !Send, !Sync by default

unsafe impl Send for Handle {}      // you promise: ownership moves, no aliasing survives
unsafe impl Sync for Handle {}      // you promise: the C session is internally synchronized

// The lie:
struct Cheat(*const u8);
unsafe impl Send for Cheat {}       // compiles; two threads now race with no warning

Nothing checks the second impl. The compiler takes your word, and the reward for lying is a program that is undefined under a condition no test reliably reproduces — the exact failure class of the last topic in this phase. This is why unsafe impl deserves the same treatment as unsafe { }:

struct Session(*mut ffi::handle);   // !Send, !Sync by default

// SAFETY: the C handle is guarded by an internal mutex; ownership moves with the
// struct and no alias to the handle survives the move between threads.
unsafe impl Send for Session {}

Adjacent evidence, not a conclusion — the same falsifiable standard as any other unsafe block, plus a # Safety-style justification if the trait defines one.

A related distinction interviewers like: a trait method can be unsafe fn too, which flips the obligations — the implementor is then trusted and the caller must uphold the contract (as with Read-style raw I/O traits), whereas the unsafe trait marker constrains who may implement at all. Knowing which side of the contract you are on tells you where the validation belongs, which is the through-line of this topic.

All three chapters — validate first, document each block, assert global properties explicitly — exist to serve one goal: keep the unsafe surface small enough that a competent reviewer can certify it in an afternoon. One module, a few dozen commented blocks, a crate root that denies unsafe everywhere else. When the surface is that small, the remaining failures are subtle rather than sloppy, and they have names: aliasing violations, lifetime lies, layout assumptions. Recognizing them on sight is Common Unsoundness Patterns, where this phase ends. The FFI declarations those patterns corrupt were built in FFI with C Libraries.