Unpin in core::marker - Rust (original) (raw)
Trait Unpin
1.33.0 · Source
pub auto trait Unpin { }Expand description
Types that do not require any pinning guarantees.
For information on what “pinning” is, see the pin module documentation.
Implementing the Unpin trait for T expresses the fact that T is pinning-agnostic: it shall not expose nor rely on any pinning guarantees. This, in turn, means that aPin-wrapped pointer to such a type can feature a fully unrestricted API. In other words, if T: Unpin, a value of type T will not be bound by the invariants which pinning otherwise offers, even when “pinned” by a Pin pointing at it. When a value of type T is pointed at by a Pin, Pin will not restrict access to the pointee value like it normally would, thus allowing the user to do anything that they normally could with a non-Pin-wrapped Ptr to that value.
The idea of this trait is to alleviate the reduced ergonomics of APIs that require the use of Pin for soundness for some types, but which also want to be used by other types that don’t care about pinning. The prime example of such an API is Future::poll. There are manyFuture types that don’t care about pinning. These futures can implement Unpin and therefore get around the pinning related restrictions in the API, while still allowing the subset of Futures which do require pinning to be implemented soundly.
For more discussion on the consequences of Unpin within the wider scope of the pinning system, see the section about Unpin in the pin module.
Unpin has no consequence at all for non-pinned data. In particular, mem::replace happily moves !Unpin data, which would be immovable when pinned (mem::replace works for any&mut T, not just when T: Unpin).
However, you cannot use mem::replace on !Unpin data which is pinned by being wrapped inside a Pin pointing at it. This is because you cannot (safely) use aPin to get a &mut T to its pointee value, which you would need to callmem::replace, and that is what makes this system work.
So this, for example, can only be done on types implementing Unpin:
use std::mem;
use std::pin::Pin;
let mut string = "this".to_string();
let mut pinned_string = Pin::new(&mut string);
// We need a mutable reference to call `mem::replace`.
// We can obtain such a reference by (implicitly) invoking `Pin::deref_mut`,
// but that is only possible because `String` implements `Unpin`.
mem::replace(&mut *pinned_string, "other".to_string());This trait is automatically implemented for almost every type. The compiler is free to take the conservative stance of marking types as Unpin so long as all of the types that compose its fields are also Unpin. This is because if a type implements Unpin, then it is unsound for that type’s implementation to rely on pinning-related guarantees for soundness,even when viewed through a “pinning” pointer! It is the responsibility of the implementor of a type that relies upon pinning for soundness to ensure that type is not marked as Unpinby adding PhantomPinned field. For more details, see the pin module docs.
When this type is used, that almost certainly means safe APIs need to use pinning to avoid the aliases from becoming invalidated. Therefore let’s mark this as !Unpin. You can always opt back in to Unpin with an impl block, provided your API is still sound while unpinned.