When is it safe to move a member value out of a pinned future?
edit: This answer is incorrect. It remains here for posterity.
Let's begin by recalling why Pin
was introduced in the first place: we want to statically ensure that self-referential futures cannot be moved, thus invalidating their internal references.
With that in mind, let's take a look at the definition of Map
.
pub struct Map<Fut, F> {
future: Fut,
f: Option<F>,
}
Map
has two fields, the first one stores a future, the second stores a closure which maps the result of that future to another value. We wish to support storing self-referential types directly in future
without placing them behind a pointer. This means that if Fut
is a self-referential type, Map
cannot be moved once it is constructed. That is why we must use Pin<&mut Map>
as the receiver for Future::poll
. If a normal mutable reference to a Map
containing a self-referential future was ever exposed to an implementor of Future
, users could cause UB using only safe code by causing the Map
to be moved using mem::replace
.
However, we don't need to support storing self-referential types in f
. If we assume that the self-referential part of a Map
is wholly contained in future
, we can freely modify f
as long as we don't allow future
to be moved.
While a self-referential closure would be very unusual, the assumption that f
be safe to move (which is equivalent to F: Unpin
) is not explicitly stated anywhere. However, we still move the value in f
in Future::poll
by calling take
! I think this is indeed a bug, but I'm not 100% sure. I think the f()
getter should require F: Unpin
which would mean Map
can only implement Future
when the closure argument is safe to be moved from behind a Pin
.
It's very possible that I'm overlooking some subtleties in the pin API here, and the implementation is indeed safe. I'm still wrapping my head around it as well.
It is all about structural pinning.
First, I will use the syntax P<T>
to mean something like impl Deref<Target = T>
— some (smart) pointer type P
that Deref::deref
s to a T
. Pin
only "applies" to / makes sense on such (smart) pointers.
Let's say we have:
struct Wrapper<Field> {
field: Field,
}
The initial question is
Can we get a
Pin<P<Field>>
from aPin<P<Wrapper<Field>>>
, by "projecting" ourPin<P<_>>
from theWrapper
to itsfield
?
This requires the basic projection P<Wrapper<Field>> -> P<Field>
, which is only possible for:
shared references (
P<T> = &T
). This is not a very interesting case given thatPin<P<T>>
alwaysderef
s toT
.unique references (
P<T> = &mut T
).
I will use the syntax &[mut] T
for this type of projection.
The question now becomes:
Can we go from
Pin<&[mut] Wrapper<Field>>
toPin<&[mut] Field>
?
The point that may be unclear from the documentation is that it is up to the creator of Wrapper
to decide!
There are two possible choices for the library author for each struct field.
There is a structural Pin
projection to that field
For instance, the pin_utils::unsafe_pinned!
macro is used to define such a projection (Pin<&mut Wrapper<Field>> -> Pin<&mut Field>
).
For the Pin
projection to be sound:
the whole struct must only implement
Unpin
when all the fields for which there is a structuralPin
projection implementUnpin
.- no implementation is allowed to use
unsafe
to move such fields out of aPin<&mut Wrapper<Field>>
(orPin<&mut Self>
whenSelf = Wrapper<Field>
). For instance,Option::take()
is forbidden.
- no implementation is allowed to use
the whole struct may only implement
Drop
ifDrop::drop
does not move any of the fields for which there is a structural projection.the struct cannot be
#[repr(packed)]
(a corollary of the previous item).
In your given future::Map
example, this is the case of the future
field of the Map
struct.
There is no structural Pin
projection to that field
For instance, the pin_utils::unsafe_unpinned!
macro is used to define such a projection (Pin<&mut Wrapper<Field>> -> &mut Field
).
In this case, that field is not considered pinned by a Pin<&mut Wrapper<Field>>
.
whether
Field
isUnpin
or not does not matter.- implementations are allowed to use
unsafe
to move such fields out of aPin<&mut Wrapper<Field>>
. For instance,Option::take()
is allowed.
- implementations are allowed to use
Drop::drop
is also allowed to move such fields,
In your given future::Map
example, this is the case of the f
field of the Map
struct.
Example of both types of projection
impl<Fut, F> Map<Fut, F> {
unsafe_pinned!(future: Fut); // pin projection -----+
unsafe_unpinned!(f: Option<F>); // not pinned --+ |
// | |
// ... | |
// | |
fn poll (mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T> {
// | |
match self.as_mut().future().poll(cx) { // <----+ required here
Poll::Pending => Poll::Pending, // |
Poll::Ready(output) => { // |
let f = self.f().take() // <--------+ allows this