Why am I not allowed to move arg in Pin::map_unchecked?

Safety note in Pin::map_unchecked says:

This function is unsafe. You must guarantee that the data you return will not move so long as the argument value does not move (for example, because it is one of the fields of that value), and also that you do not move out of the argument you receive to the interior function.

Why? The only problem I could potentially see about it is something like this:

  1. Create a Pin<&RefCell<T>>
  2. Turn Pin<&RefCell<T>> into Pin<&T> using Pin::map_unchecked
  3. Move T using some (shared) reference to RefCell.

But that doesn't seem to be the case, because the documentation clearly says about moving argument that I receive to the interior function (so moving from within the closure - before I create a Pin<&T>). Does the description make assumption I may have created Pin<&T> before? I think the documentation here is at least unclear.

The highlighted sentence doesn’t make too much sense for map_unchecked. It looks to me like the documentation was copy-pasted from map_unchecked_mut, where the “You must guarantee that […] you do not move out of the argument you receive to the interior function.” provision makes a lot more sense. For map_unchecked though, the &T argument to the mapped function doesn’t provide anything above what Pin<&T> already gave us, as Pin<&T> -> &T is safe via dereferencing or get_ref, anyways - so the unsafe part is merely about the return &U being wrapped into Pin<&U>.

Regarding your comment / example with RefCell, I cannot quite follow that. Note however that RefCell cannot soundly do structural pinning anyways, since a Pin<&RefCell<T>> allows mutable (non-pinned) access to the contained value via get_ref (which gives us the &RefCell<T>) and borrow_mut (which then gives &mut T), anyways.


The RefCell example was brought by another user trying to explain (I believe) the highlithed sentence on users forum here.

Btw. What's the most "clean" way to propose such a small documentation change? Wouldn't PR be an "overkill" for this?

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.