Rust Reference ยท Smart Pointers and Memory
Rust Pin<P> type
Reference for Rust Pin<P> and Unpin: Box::pin, pin!, as_mut, get_mut, PhantomPinned, self-referential structs and why async futures are pinned.
Pin<P> wraps a pointer type P (such as Box<T>, &mut T or Rc<T>) and promises that the value it points to will not be moved in memory until it is dropped. That promise matters for values that contain pointers into themselves, the most important example being the state machines the compiler generates for async blocks.
Most types do not care about moving. They implement the auto trait Unpin, and for those Pin<&mut T> behaves like a plain &mut T (you can get the reference back with get_mut or Pin::new). Only !Unpin types, such as futures and anything containing PhantomPinned, are actually held in place.
use std::pin::Pin; let boxed: Pin<Box<i32>> = Box::pin(5); assert_eq!(*boxed, 5);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
pub struct Pin<Ptr> { /* private */ } impl<Ptr: Deref<Target: Unpin>> Pin<Ptr> { pub fn new(pointer: Ptr) -> Pin<Ptr>; pub fn into_inner(pin: Pin<Ptr>) -> Ptr; } impl<Ptr: Deref> Pin<Ptr> { pub unsafe fn new_unchecked(pointer: Ptr) -> Pin<Ptr>; pub fn as_ref(&self) -> Pin<&Ptr::Target>; } impl<Ptr: DerefMut> Pin<Ptr> { pub fn as_mut(&mut self) -> Pin<&mut Ptr::Target>; pub fn set(&mut self, value: Ptr::Target) where Ptr::Target: Sized; } impl<'a, T: ?Sized> Pin<&'a mut T> { pub fn get_mut(self) -> &'a mut T where T: Unpin; pub unsafe fn get_unchecked_mut(self) -> &'a mut T; }
| Item | Description |
|---|---|
Pin::new(p) |
Safe constructor, only for pointers to Unpin targets. |
Box::pin(v) |
Moves v to the heap and returns Pin<Box<T>>; works for any T. |
std::pin::pin!(v) |
Pins a value on the stack and gives a Pin<&mut T>; no unsafe needed. |
Pin::new_unchecked |
Unsafe: you promise the target is never moved afterwards. |
as_mut() / as_ref() |
Reborrow the pinned pointer without consuming it. |
get_mut() |
Back to &mut T, only if T: Unpin. |
get_unchecked_mut() |
Unsafe &mut T; you must not move out of it. |
set(v) |
Overwrite the pointee in place (drops the old value). |
Edge cases. Pinning does not stop a value from being dropped or from being mutated in place; it only forbids moving it (mem::swap, mem::replace, moving out). Drop::drop takes &mut self even for pinned types, so drop code must not move fields out.
Usage notes
- Futures are
!Unpinin general, so executors store them asPin<Box<dyn Future<Output = T>>>.Future::polltakesself: Pin<&mut Self>for exactly that reason. Box::pinis the easy default. Usepin!when the value can stay in the current stack frame (for example, to callpollorselect!-like code).- Pinning is "structural" when a field is also considered pinned. Safe projection helpers live in crates; by hand you need
unsafe. Unpinis an auto trait: structs areUnpinif all fields are.PhantomPinnedopts a type out.- You rarely write
Pinin application code. You meet it inFuture::pollsignatures, in manual future implementations and in self-referential data structures.