pin-project-lite

This crate is the silent workhorse behind most async Rust code. It solves the pin-projection problem with zero runtime overhead—literally just compile-time macro expansion. I've used it extensively in custom Future and Stream implementations where you need to safely project Pin<&mut Self> to pinned fields. The macro generates exactly the code you'd write by hand, but without the boilerplate and unsafety bugs.

From an ops perspective, it's perfect: no runtime cost, no allocations, no dependencies beyond proc-macro2 and minimal compilation overhead. The generated code is trivial to inspect and debug. Error messages are clear when you mess up pinning invariants. It has never caused issues under load because there's literally nothing there at runtime—just safe projections.

The API is stable and well-understood. Breaking changes between versions are extremely rare and well-documented. For building async primitives and custom combinators, this is the standard solution. It integrates seamlessly with tokio, futures, and any async runtime without adding dependency bloat.

pin-project-lite delivers exactly what it promises: a lightweight, declarative macro for safe pin projection. The `pin_project!` macro is refreshingly straightforward - you annotate fields with `#[pin]` and it generates the boilerplate for safe structural pinning. Unlike the full pin-project crate, it uses declarative macros which means faster compile times and simpler mental model, though with some limitations.

Day-to-day usage is excellent. The macro syntax is intuitive and feels like native Rust. Error messages are clear when you violate pinning invariants, pointing directly to problematic field access. The crate documentation includes precise examples of both simple and complex use cases, including Drop implementation patterns. IDE support works flawlessly since it's pure declarative macros - no proc-macro black magic that confuses rust-analyzer.

The main limitation is intentional: it doesn't support some advanced features like `!Unpin` impls or where-clause configurations that full pin-project offers. For 95% of async runtime and combinator implementations, these restrictions don't matter. The compile-time performance gain is noticeable in larger projects.

Using pin-project-lite in async Rust projects has been consistently pleasant. The macro generates clean projection code without the complexity of a full procedural macro, keeping compile times low. The `pin_project!` macro syntax is straightforward—you simply annotate fields with `#[pin]` and the macro generates safe projection methods automatically.

The error messages are remarkably clear for a macro-based library. When you forget to mark a field as pinned or try to move out of a pinned field, the compiler errors point directly to the issue with helpful context. The documentation includes practical examples of implementing Future and Stream, which are the primary use cases. IDE support works well since it's a declarative macro, though you won't get autocompletion inside the macro itself.

Day-to-day, it just works. Once you understand Rust's pinning semantics (the real learning curve), pin-project-lite makes implementing pin-safe types trivial. It's a focused tool that solves one problem exceptionally well without feature bloat.