Add a stack-pin!-ning macro to core::pin.

[danielhenrymantilla]

• Tracking Issue for core::pin::pin! #93178

pin! allows pinning a value to the stack. Thanks to being implemented in the stdlib, which gives access to macro macros, and to the private .pointer field of the Pin wrapper, it was recently discovered (archive link), contrary to popular belief, that it is actually possible to implement and feature such a macro:

let foo: Pin<&mut PhantomPinned> = pin!(PhantomPinned);
stuff(foo);

or, directly:

stuff(pin!(PhantomPinned));

• For context, historically, this used to require one of the two following syntaxes:

  • let foo = PhantomPinned;
    pin!(foo);
    stuff(foo);

  • pin! {
        let foo = PhantomPinned;
    }
    stuff(foo);

This macro thus allows, for instance, doing things like:

fn block_on<T>(fut: impl Future<Output = T>) -> T {
    // Pin the future so it can be polled.
-   let mut fut = Box::pin(fut);
+   let mut fut = pin!(fut);

    // Create a new context to be passed to the future.
    let t = thread::current();
    let waker = Arc::new(ThreadWaker(t)).into();
    let mut cx = Context::from_waker(&waker);

    // Run the future to completion.
    loop {
        match fut.as_mut().poll(&mut cx) {
            Poll::Ready(res) => return res,
            Poll::Pending => thread::park(),
        }
    }
}

• c.f., https://doc.rust-lang.org/1.58.1/alloc/task/trait.Wake.html

And so on, and so forth.

I don't think such an API can get better than that, barring full featured language support (&pin references or something), so I see no reason not to start experimenting with featuring this in the stdlib already 🙂

• cc @rust-lang/wg-async-foundations [EDIT: this doesn't seem to have pinged anybody 😩, thanks @yoshuawuyts for the real ping]

r? @joshtriplett

---

Docs preview

video1167605346.mp4

---

Implementation

The implementation ends up being dead simple (so much it's embarrassing):

pub macro pin($value:expr $(,)?) {
    Pin { pointer: &mut { $value } }
}

and voilà!

• The key for it working lies in the rules governing the scope of anonymous temporaries.

Comments and context

This is Pin::new_unchecked(&mut { $value }), so, for starters, let's
review such a hypothetical macro (that any user-code could define):

macro_rules! pin {( $value:expr ) => (
    match &mut { $value } { at_value => unsafe { // Do not wrap `$value` in an `unsafe` block.
        $crate::pin::Pin::<&mut _>::new_unchecked(at_value)
    }}
)}

Safety:

• type P = &mut _. There are thus no pathological Deref{,Mut} impls that would break Pin's invariants.
• { $value } is braced, making it a block expression, thus moving the given $value, and making it become an anonymous temporary.
  By virtue of being anonynomous, it can no longer be accessed, thus preventing any attemps to mem::replace it or mem::forget it, etc.

This gives us a pin! definition that is sound, and which works, but only in certain scenarios:

• If the pin!(value) expression is directly fed to a function call:
  let poll = pin!(fut).poll(cx);

• If the pin!(value) expression is part of a scrutinee:

  match pin!(fut) { pinned_fut => {
      pinned_fut.as_mut().poll(...);
      pinned_fut.as_mut().poll(...);
  }} // <- `fut` is dropped here.

Alas, it doesn't work for the more straight-forward use-case: let bindings.

let pinned_fut = pin!(fut); // <- temporary value is freed at the end of this statement
pinned_fut.poll(...) // error[E0716]: temporary value dropped while borrowed
                     // note: consider using a `let` binding to create a longer lived value

• Issues such as this one are the ones motivating RFC: Better temporary lifetimes (so e.g. .as_slice() works) rfcs#66

This makes such a macro incredibly unergonomic in practice, and the reason most macros out there had to take the path of being a statement/binding macro (e.g., pin!(future);) instead of featuring the more intuitive ergonomics of an expression macro.

Luckily, there is a way to avoid the problem. Indeed, the problem stems from the fact that a temporary is dropped at the end of its enclosing statement when it is part of the parameters given to function call, which has precisely been the case with our Pin::new_unchecked()!

For instance,

let p = Pin::new_unchecked(&mut <temporary>);

becomes:

let p = { let mut anon = <temporary>; &mut anon };

However, when using a literal braced struct to construct the value, references to temporaries can then be taken. This makes Rust change the lifespan of such temporaries so that they are, instead, dropped at the end of the enscoping block.

For instance,

let p = Pin { pointer: &mut <temporary> };

becomes:

let mut anon = <temporary>;
let p = Pin { pointer: &mut anon };

which is exactly what we want.

Finally, we don't hit problems w.r.t. the privacy of the pointer field, or the unqualified Pin name, thanks to decl_macros being fully hygienic (def_site hygiene).

---

TODO

• Add compile-fail tests with attempts to break the Pin invariants thanks to the macro (e.g., try to access the private .pointer field, or see what happens if such a pin is used outside its enscoping scope (borrow error));
• Follow-up stuff:
  • Try to experiment with adding pin! to the prelude: this may require to be handled with some extra care, as it may lead to issues reminiscent of those of assert_matches!: Is there a gentler way to land the assert_matches macro? #82913
  • Create the tracking issue.

[danielhenrymantilla]

@rustbot modify labels: +T-libs-api +A-async-await +F-decl_macro +A-pin

[ibraheemdev]

👍, but I think this deserves a beginner-friendly explanation on top of why this is needed/useful, e.g: https://docs.rs/tokio/latest/tokio/macro.pin.html. Also, this needs a tracking issue.

[yoshuawuyts]

cc @rust-lang/wg-async-foundations

[cramertj]

What led to the decision to call this pin! rather than pin_mut!? I'm aware of inconsistency here between futures and tokio, and it would be good to resolve.

Personally, I think that since there are known use-cases for Pin<&T>, it seems like it would be valuable to offer both pin_ref and pin_mut, as is standard in other library APIs.

[cramertj]

(That said, it also requires move-access to a value in order to use this macro even in the &-case, and the resulting Pin<&mut T> can be converted into a Pin<&T>, so I'd understand only offering this one.)

[danielhenrymantilla]

@cramertj Right now I just followed the more pervasive name out there, but I have no opinions on this matter whatsoever.
In a way, I even prefer pin_mut!, but I have to admit I like the look of that s/Box::pin/pin!/diff 😄. Ideally we'd have had something like <&mut _>::pin! or mut_ref::pin!, so as to be consistent with Box::pin naming, but lacking that, I can see the appeal of pin_mut!.

FWIW, now that the macro is so ergonomic, there is an argument to be made for pin_ref! (besides sheer symmetry):
let x = pin_mut!(…).as_ref(); will yield a "dangling"/unusable x, because the .as_ref() then breaks the temporary promotion.

So with all that being said, I personally lean ever so slightly towards pin_mut!, but let's see what others think on the matter. It's something easy to change before the stabilization anyways. Lemme add the concern to the tracking issue.

[eddyb]

cc @nikomatsakis This could maybe use a more direct reference to the let RHS temporaries "scope extension" rules, but I forget where this is described, the best I can find is a section in the reference.

[danielhenrymantilla]

@eddyb agreed, I searched among the RFCs and surprisingly there was no normative stuff. But that reference link you provided is great! I'll add a permalink to it to the comments tomorrow

[danielhenrymantilla]

The exact rules for temporary lifetime extension are subject to change. This is describing the current behavior only.

Hmm, isn't it super-hard for these rules to change? Both reducing and enlarging the scope of temporaries can break code out there, both at compile-time (if borrows are involved) or at runtime (if lock guards are involved).

[eholk]

This looks awesome!

I suppose I'd have a slight preference towards pin_mut! as well, for symmetry with similar APIs, but I don't feel strongly. Having a short name like pin! is also nice.

[taiki-e]

I would prefer pin! over pin_mut!. (I've considered its renaming in the past in pin-utils and futures: rust-lang/pin-utils#32)

Considering the stack pinning utilities for shared references are unneeded, we probably don't need mut of pin_mut! macro.

[Darksonn]

I know that people sometimes claim that Pin<&T> is useful in some cases, but I have yet to see an actual use-case. I support the name pin!.

[m-ou-se]

@bors r+

[bors]

📌 Commit bf2a9dc has been approved by m-ou-se

[bors]

⌛ Testing commit bf2a9dc with merge 6421a49...

[bors]

☀️ Test successful - checks-actions
Approved by: m-ou-se
Pushing 6421a49 to master...

[rust-timer]

Finished benchmarking commit (6421a49): comparison url.

Summary: This benchmark run did not return any relevant results.

If you disagree with this performance assessment, please file an issue in rust-lang/rustc-perf.

@rustbot label: -perf-regression