async_iterator)async_iterator)None if the async iterator is exhausted. Read morecoroutine_trait)Converts a Box<T> into a Pin<Box<T>>. If T does not implement Unpin, then\n*boxed will be pinned in memory and unable to be moved.
This conversion does not allocate on the heap and happens in place.
\nThis is also available via Box::into_pin.
Constructing and pinning a Box with <Pin<Box<T>>>::from(Box::new(x))\ncan also be written more concisely using Box::pin(x).\nThis From implementation is useful if you already have a Box<T>, or you are\nconstructing a (pinned) Box in a different way than with Box::new.
true if the underlying future should no longer be polled.true if the stream should no longer be polled.Constructs a new Pin<Ptr> around a pointer to some data of a type that\nimplements Unpin.
Unlike Pin::new_unchecked, this method is safe because the pointer\nPtr dereferences to an Unpin type, which cancels the pinning guarantees.
use std::pin::Pin;\n\nlet mut val: u8 = 5;\n\n// Since `val` doesn't care about being moved, we can safely create a \"facade\" `Pin`\n// which will allow `val` to participate in `Pin`-bound apis without checking that\n// pinning guarantees are actually upheld.\nlet mut pinned: Pin<&mut u8> = Pin::new(&mut val);Unwraps this Pin<Ptr>, returning the underlying pointer.
Doing this operation safely requires that the data pointed at by this pinning pointer\nimplements Unpin so that we can ignore the pinning invariants when unwrapping it.
use std::pin::Pin;\n\nlet mut val: u8 = 5;\nlet pinned: Pin<&mut u8> = Pin::new(&mut val);\n\n// Unwrap the pin to get the underlying mutable reference to the value. We can do\n// this because `val` doesn't care about being moved, so the `Pin` was just\n// a \"facade\" anyway.\nlet r = Pin::into_inner(pinned);\nassert_eq!(*r, 5);Constructs a new Pin<Ptr> around a reference to some data of a type that\nmay or may not implement Unpin.
If pointer dereferences to an Unpin type, Pin::new should be used\ninstead.
This constructor is unsafe because we cannot guarantee that the data\npointed to by pointer is pinned. At its core, pinning a value means making the\nguarantee that the value’s data will not be moved nor have its storage invalidated until\nit gets dropped. For a more thorough explanation of pinning, see the pin module docs.
If the caller that is constructing this Pin<Ptr> does not ensure that the data Ptr\npoints to is pinned, that is a violation of the API contract and may lead to undefined\nbehavior in later (even safe) operations.
By using this method, you are also making a promise about the Deref,\nDerefMut, and Drop implementations of Ptr, if they exist. Most importantly, they\nmust not move out of their self arguments: Pin::as_mut and Pin::as_ref\nwill call DerefMut::deref_mut and Deref::deref on the pointer type Ptr\nand expect these methods to uphold the pinning invariants.\nMoreover, by calling this method you promise that the reference Ptr\ndereferences to will not be moved out of again; in particular, it\nmust not be possible to obtain a &mut Ptr::Target and then\nmove out of that reference (using, for example mem::swap).
For example, calling Pin::new_unchecked on an &'a mut T is unsafe because\nwhile you are able to pin it for the given lifetime 'a, you have no control\nover whether it is kept pinned once 'a ends, and therefore cannot uphold the\nguarantee that a value, once pinned, remains pinned until it is dropped:
use std::mem;\nuse std::pin::Pin;\n\nfn move_pinned_ref<T>(mut a: T, mut b: T) {\n unsafe {\n let p: Pin<&mut T> = Pin::new_unchecked(&mut a);\n // This should mean the pointee `a` can never move again.\n }\n mem::swap(&mut a, &mut b); // Potential UB down the road ⚠️\n // The address of `a` changed to `b`'s stack slot, so `a` got moved even\n // though we have previously pinned it! We have violated the pinning API contract.\n}A value, once pinned, must remain pinned until it is dropped (unless its type implements\nUnpin). Because Pin<&mut T> does not own the value, dropping the Pin will not drop\nthe value and will not end the pinning contract. So moving the value after dropping the\nPin<&mut T> is still a violation of the API contract.
Similarly, calling Pin::new_unchecked on an Rc<T> is unsafe because there could be\naliases to the same data that are not subject to the pinning restrictions:
use std::rc::Rc;\nuse std::pin::Pin;\n\nfn move_pinned_rc<T>(mut x: Rc<T>) {\n // This should mean the pointee can never move again.\n let pin = unsafe { Pin::new_unchecked(Rc::clone(&x)) };\n {\n let p: Pin<&T> = pin.as_ref();\n // ...\n }\n drop(pin);\n\n let content = Rc::get_mut(&mut x).unwrap(); // Potential UB down the road ⚠️\n // Now, if `x` was the only reference, we have a mutable reference to\n // data that we pinned above, which we could use to move it as we have\n // seen in the previous example. We have violated the pinning API contract.\n}Particular care is required when using Pin::new_unchecked in a closure:\nPin::new_unchecked(&mut var) where var is a by-value (moved) closure capture\nimplicitly makes the promise that the closure itself is pinned, and that all uses\nof this closure capture respect that pinning.
use std::pin::Pin;\nuse std::task::Context;\nuse std::future::Future;\n\nfn move_pinned_closure(mut x: impl Future, cx: &mut Context<'_>) {\n // Create a closure that moves `x`, and then internally uses it in a pinned way.\n let mut closure = move || unsafe {\n let _ignore = Pin::new_unchecked(&mut x).poll(cx);\n };\n // Call the closure, so the future can assume it has been pinned.\n closure();\n // Move the closure somewhere else. This also moves `x`!\n let mut moved = closure;\n // Calling it again means we polled the future from two different locations,\n // violating the pinning API contract.\n moved(); // Potential UB ⚠️\n}When passing a closure to another API, it might be moving the closure any time, so\nPin::new_unchecked on closure captures may only be used if the API explicitly documents\nthat the closure is pinned.
The better alternative is to avoid all that trouble and do the pinning in the outer function\ninstead (here using the pin! macro):
use std::pin::pin;\nuse std::task::Context;\nuse std::future::Future;\n\nfn move_pinned_closure(mut x: impl Future, cx: &mut Context<'_>) {\n let mut x = pin!(x);\n // Create a closure that captures `x: Pin<&mut _>`, which is safe to move.\n let mut closure = move || {\n let _ignore = x.as_mut().poll(cx);\n };\n // Call the closure, so the future can assume it has been pinned.\n closure();\n // Move the closure somewhere else.\n let mut moved = closure;\n // Calling it again here is fine (except that we might be polling a future that already\n // returned `Poll::Ready`, but that is a separate problem).\n moved();\n}Gets a shared reference to the pinned value this Pin points to.
This is a generic method to go from &Pin<Pointer<T>> to Pin<&T>.\nIt is safe because, as part of the contract of Pin::new_unchecked,\nthe pointee cannot move after Pin<Pointer<T>> got created.\n“Malicious” implementations of Pointer::Deref are likewise\nruled out by the contract of Pin::new_unchecked.
Gets a mutable reference to the pinned value this Pin<Ptr> points to.
This is a generic method to go from &mut Pin<Pointer<T>> to Pin<&mut T>.\nIt is safe because, as part of the contract of Pin::new_unchecked,\nthe pointee cannot move after Pin<Pointer<T>> got created.\n“Malicious” implementations of Pointer::DerefMut are likewise\nruled out by the contract of Pin::new_unchecked.
This method is useful when doing multiple calls to functions that consume the\npinning pointer.
\nuse std::pin::Pin;\n\nimpl Type {\n fn method(self: Pin<&mut Self>) {\n // do something\n }\n\n fn call_method_twice(mut self: Pin<&mut Self>) {\n // `method` consumes `self`, so reborrow the `Pin<&mut Self>` via `as_mut`.\n self.as_mut().method();\n self.as_mut().method();\n }\n}Gets Pin<&mut T> to the underlying pinned value from this nested Pin-pointer.
This is a generic method to go from Pin<&mut Pin<Pointer<T>>> to Pin<&mut T>. It is\nsafe because the existence of a Pin<Pointer<T>> ensures that the pointee, T, cannot\nmove in the future, and this method does not enable the pointee to move. “Malicious”\nimplementations of Ptr::DerefMut are likewise ruled out by the contract of\nPin::new_unchecked.
Assigns a new value to the memory location pointed to by the Pin<Ptr>.
This overwrites pinned data, but that is okay: the original pinned value’s destructor gets\nrun before being overwritten and the new value is also a valid value of the same type, so\nno pinning invariant is violated. See the pin module documentation\nfor more information on how this upholds the pinning invariants.
use std::pin::Pin;\n\nlet mut val: u8 = 5;\nlet mut pinned: Pin<&mut u8> = Pin::new(&mut val);\nprintln!(\"{}\", pinned); // 5\npinned.set(10);\nprintln!(\"{}\", pinned); // 10Unwraps this Pin<Ptr>, returning the underlying Ptr.
This function is unsafe. You must guarantee that you will continue to\ntreat the pointer Ptr as pinned after you call this function, so that\nthe invariants on the Pin type can be upheld. If the code using the\nresulting Ptr does not continue to maintain the pinning invariants that\nis a violation of the API contract and may lead to undefined behavior in\nlater (safe) operations.
Note that you must be able to guarantee that the data pointed to by Ptr\nwill be treated as pinned all the way until its drop handler is complete!
For more information, see the pin module docs
If the underlying data is Unpin, Pin::into_inner should be used\ninstead.