Rust Pin & Async Traits [2026] Driver Reference Guide

Rust’s pinning model is still the boundary between elegant async code and subtle UB-shaped mistakes, especially in driver code that polls state machines, DMA-like buffers, or transport futures by hand. In Rust 1.75, native async fn in traits became stable, which removes a lot of boilerplate, but it does not remove the need to understand Pin, structural projection, Send bounds, and dyn-compatibility tradeoffs.

• Rust 1.75 stabilized async fn in traits via return-position impl Future.
• async fn traits are still not dyn-compatible, so generic fast paths and boxed-object paths remain separate decisions.
• pin-project 1.1.11 is the ergonomic choice when a driver struct mixes pinned and unpinned fields.
• pin-project-lite 0.2.17 exists mainly to avoid proc-macro dependencies, not to win runtime performance.

Quick Map

What Changed

• Rust 1.75 made trait methods returning hidden futures stable through native async fn in traits.
• The Rust team still recommends care with public traits because callers cannot add future bounds later.
• For public async traits that must support multithreaded executors, trait-variant 0.1.2 is the official ergonomic bridge.
• For dyn dispatch, async-trait 0.1.89 remains the practical boxed-future fallback.

Choose The Right Tool

Live Search And Shortcuts

Markup For A Live Filter

<div class='not-prose mb-6'>
  <label for='cheat-filter' class='sr-only'>Filter the cheat sheet</label>
  <input
    id='cheat-filter'
    type='search'
    placeholder='Filter by pin, trait, send, drop...'
    class='w-full rounded-xl border px-4 py-3'
  />
</div>

<div id='cheat-grid'>
  <section data-filter-item data-tags='pin stack local future'>...</section>
  <section data-filter-item data-tags='trait send public async'>...</section>
  <section data-filter-item data-tags='drop projection destructor'>...</section>
</div>

Minimal Filter Script

const input = document.querySelector('#cheat-filter');
const items = [...document.querySelectorAll('[data-filter-item]')];

function applyFilter() {
  const q = input.value.trim().toLowerCase();
  for (const item of items) {
    const haystack = (item.textContent + ' ' + (item.dataset.tags || '')).toLowerCase();
    item.hidden = q && !haystack.includes(q);
  }
}

document.addEventListener('keydown', (event) => {
  if (event.key === '/' && document.activeElement !== input) {
    event.preventDefault();
    input.focus();
  }

  if (event.key === 'Escape' && document.activeElement === input) {
    input.value = '';
    applyFilter();
    input.blur();
  }
});

input.addEventListener('input', applyFilter);

Suggested Keyboard Shortcuts

Commands And Snippets By Purpose

use std::future::Future;
use std::pin::pin;

async fn run_driver() {}

fn poll_once(cx: &mut std::task::Context<'_>) {
    let fut = pin!(run_driver());
    let _ = Future::poll(fut.as_ref(), cx);
}

use std::future::Future;
use std::pin::Pin;

async fn run_driver() {}

let fut: Pin<Box<dyn Future<Output = ()>>> = Box::pin(run_driver());

use std::future::Future;
use std::io;
use std::pin::Pin;
use std::task::{Context, Poll};
use pin_project::pin_project;

#[pin_project]
struct DriverInit<F> {
    #[pin]
    init: F,
    retries: u8,
}

impl<F> Future for DriverInit<F>
where
    F: Future<Output = io::Result<()>>,
{
    type Output = io::Result<()>;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let this = self.project();
        this.init.poll(cx)
    }
}

#[trait_variant::make(DeviceIo: Send)]
pub trait LocalDeviceIo {
    async fn read_frame(&mut self, buf: &mut [u8]) -> usize;
    async fn flush(&mut self);
}

use async_trait::async_trait;

#[async_trait]
trait DeviceIo {
    async fn read_frame(&mut self, buf: &mut [u8]) -> usize;
}

fn register(dev: Box<dyn DeviceIo + Send>) {
    let _ = dev;
}

Configuration

Cargo.toml Presets

[dependencies]
pin-project = "1"
pin-project-lite = "0.2"
trait-variant = "0.1.2"
async-trait = "0.1.89"

• Use pin-project 1.1.11 when you want the richer macro surface, enum support, #[pinned_drop], and better diagnostics.
• Use pin-project-lite 0.2.17 when your main goal is avoiding proc-macro dependencies.
• Set your practical floor to Rust 1.75 if you want native async traits in library code.
• Keep async-trait isolated to object-safe seams so boxed futures do not spread across hot paths.

If you want to normalize the snippets before shipping internal docs or runbooks, the TechBytes Code Formatter is a clean last pass.

Advanced Usage

Manual Poll Driver Pattern

• Polling a field future directly avoids extra wrapper allocations.
• Projection keeps the field borrow precise, which matters once your driver grows multiple states.
• This is where Pin stops being theory and becomes a mechanical requirement.

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use pin_project::pin_project;

#[pin_project]
struct ConnectThenRun<C, R> {
    #[pin]
    connect: C,
    #[pin]
    run: Option<R>,
}

impl<C, R> Future for ConnectThenRun<C, R>
where
    C: Future<Output = R>,
    R: Future<Output = ()>,
{
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        let mut this = self.project();

        if let Some(run) = this.run.as_mut().as_pin_mut() {
            return run.poll(cx);
        }

        let next = std::task::ready!(this.connect.as_mut().poll(cx));
        this.run.set(Some(next));

        if let Some(run) = this.run.as_mut().as_pin_mut() {
            run.poll(cx)
        } else {
            Poll::Pending
        }
    }
}

Custom Drop Without Moving Pinned Fields

• #[pinned_drop] lets teardown logic see Pin<&mut Self>.
• That keeps destructors honest when pinned fields must never be moved during cleanup.

use std::pin::Pin;
use pin_project::{pin_project, pinned_drop};

#[pin_project(PinnedDrop)]
struct Tx<F> {
    #[pin]
    flush: F,
    closed: bool,
}

#[pinned_drop]
impl<F> PinnedDrop for Tx<F> {
    fn drop(self: Pin<&mut Self>) {
        let this = self.project();
        *this.closed = true;
    }
}

Review Checklist

• Do all structurally pinned fields carry #[pin]?
• Does every public async trait make an explicit Send decision?
• Are boxed futures confined to dyn-dispatch boundaries?
• Does drop logic avoid taking &mut Self on pinned types?
• Are local one-shot futures using pin! instead of unnecessary boxing?

FAQs

When do I actually need Pin in an async driver?

You need Pin when the polled future or state machine must not move after polling begins, or when a safe API promises that certain fields stay at a stable address. That shows up quickly in manual poll implementations and any self-referential or projection-heavy driver type.

Should I replace #[async_trait] everywhere now?

No. Replace it on static-dispatch hot paths first, because native async traits remove boxing there. Keep #[async_trait] where dyn dispatch is part of the API surface or migration cost is higher than the runtime win.

What is the real difference between pin-project and pin-project-lite?

pin-project is the feature-rich ergonomic choice. pin-project-lite exists mainly to avoid proc-macro dependencies, and its docs explicitly say there is almost no difference in generated code.

Why does my async trait fail when I try Box<dyn Trait>?

Because native async trait methods hide a future type, which makes the trait not dyn-compatible under today’s Rust Reference rules. Use #[async_trait] or redesign the object-safe boundary.