Higher-Rank Trait Bounds (HRTB) & Structural Pinning

Higher-Rank Trait Bounds (HRTBs)

Standard generics allow parameterizing a type over a specific lifetime (e.g., where T: 'a). However, high-throughput asynchronous parsers, tokenizers, and closures often need to accept a reference with any arbitrary lifetime chosen dynamically by the caller. This is expressed via the for<'a> syntax:

// Accepts a parser function that works for ANY lifetime 'a of the input slice
pub struct ZeroCopyParser
where
    F: for<'a> Fn(&'a [u8]) -> Result<&'a str, ParseError>,
{
    parse_fn: F,
}

Structural Pinning: Pin<&mut T>

When an asynchronous function contains an .await point across which local references are held, the compiler generates a state machine containing a self-referential pointer. If that struct is moved in memory (e.g. copied to another stack frame or reallocated), the internal pointer points to invalidated memory. Pin solves this at compile time:

use std::pin::Pin;
use std::marker::PhantomPinned;

pub struct SelfReferentialAsyncBuffer {
    data: [u8; 1024],
    internal_slice_ptr: *const [u8],
    _pin: PhantomPinned, // Opts OUT of the Unpin auto-trait
}

impl SelfReferentialAsyncBuffer {
    pub fn new() -> Self {
        Self {
            data: [0u8; 1024],
            internal_slice_ptr: std::ptr::null(),
            _pin: PhantomPinned,
        }
    }

    // Must be pinned before initializing internal pointer!
    pub fn init(self: Pin<&mut Self>) {
        let this = unsafe { self.get_unchecked_mut() };
        this.internal_slice_ptr = &this.data[..];
    }
}