Tracking Issue for pin_deref_mut

[jonhoo]

Feature gate: #![feature(pin_deref_mut)]

This is a tracking issue for Pin::as_deref_mut.

The feature adds the method as_deref_mut to Pin, which allow a safe transformation from a Pin<&mut Pin<P>> to a Pin<&mut P::Target>.

Public API

impl<Ptr> Pin<Ptr> {
    pub fn as_deref_mut(self: Pin<&mut Pin<Ptr>>) -> Pin<&mut Ptr::Target>
    where
        Ptr: DerefMut;
}

Steps / History

• Remove P: Unpin bound on impl Future for Pin #81363
• Put Pin::as_deref_mut in impl Pin<Ptr> / rearrange Pin methods #129449
• Stabilize Pin::as_deref_mut() #129424

Unresolved Questions

• None yet.

[coolreader18]

Are there any remaining blockers on this? It's a pretty useful function for blanket impls for traits with poll methods (e.g. Future already uses it in its impl<P> Future for Pin<P> impl).

[jonhoo]

Not that I know of — given it touches the Pin machinery, I suspect it should go through an actual FCP, but I'll let others be the judge of that :)

[dtolnay]

Currently this method is located in its own solitary impl block:

impl<'a, Ptr: DerefMut> Pin<&'a mut Pin<Ptr>> {
    pub fn as_deref_mut(self) -> Pin<&'a mut Ptr::Target>;
}

I'd like to consider changing it to:

impl<Ptr> Pin<Ptr> {
    pub fn as_deref_mut(self: Pin<&mut Pin<Ptr>>) -> Pin<&mut Ptr::Target>
    where
        Ptr: DerefMut;
}

Some advantages:

• Synergy with the existing as_ref and as_mut signatures (stable since Rust 1.33)
• Lifetime elision reduces noise in the signature
• Turbofish less verbose: Pin::<&mut T>::as_deref_mut vs Pin::<&mut Pin<&mut T>>::as_deref_mut

impl<Ptr> Pin<Ptr> {
    pub fn as_ref(&self) -> Pin<&Ptr::Target>
    where
        Ptr: Deref;

    pub fn as_mut(&mut self) -> Pin<&mut Ptr::Target>
    where
        Ptr: DerefMut;
}

[thynson]

Any concern blocks this from stablization?

[jonhoo]

@dtolnay I agree — that is better 👍

[coolreader18]

Would it be possible to start an FCP on this?

[dtolnay]

@rust-lang/libs-api:
@rfcbot fcp merge

.as_deref_mut() is like .get_mut().as_mut(), but without enforcing an unnecessary Ptr: Unpin.
It is like unsafe { .get_unchecked_mut() }.as_mut(), but is unconditionally safe.

The use case arises in real-world code when you are implementing a trait that takes self: Pin<&mut Self> where the Self type of your impl is Pin<Ptr>. So what you have is something like Pin<&mut Pin<Box<T>>>, and want to delegate to the impl for T which takes Pin<&mut T>. Some examples:

In tokio: impl<P> AsyncRead for Pin<P>

In hyper: impl<P> Read for Pin<P>

In futures: impl<P> Stream for Pin<P>

In actix: impl<P, A> ActorFuture<A> for Pin<P>

In libcore:

rust/library/core/src/future/future.rs

Lines 116 to 122 in bf662eb

	impl<P> Future for Pin<P>
	where
	P: ops::DerefMut<Target: Future>,
	{
	type Output = <<P as ops::Deref>::Target as Future>::Output;
	fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {

rust/library/core/src/async_iter/async_iter.rs

Lines 99 to 106 in bf662eb

	impl<P> AsyncIterator for Pin<P>
	where
	P: DerefMut,
	P::Target: AsyncIterator,
	{
	type Item = <P::Target as AsyncIterator>::Item;
	fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.