///
/// Unlike `Pin::new_unchecked`, this method is safe because the pointer
/// `P` dereferences to an [`Unpin`] type, which cancels the pinning guarantees.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use std::pin::Pin;
+ ///
+ /// let mut val: u8 = 5;
+ /// // We can pin the value, since it doesn't care about being moved
+ /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val);
+ /// ```
#[inline(always)]
#[rustc_const_unstable(feature = "const_pin", issue = "76654")]
#[stable(feature = "pin", since = "1.33.0")]
/// Unwraps this `Pin<P>` returning the underlying pointer.
///
- /// This requires that the data inside this `Pin` is [`Unpin`] so that we
+ /// This requires that the data inside this `Pin` implements [`Unpin`] so that we
/// can ignore the pinning invariants when unwrapping it.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use std::pin::Pin;
+ ///
+ /// let mut val: u8 = 5;
+ /// let pinned: Pin<&mut u8> = Pin::new(&mut val);
+ /// // Unwrap the pin to get a reference to the value
+ /// let r = Pin::into_inner(pinned);
+ /// assert_eq!(*r, 5);
+ /// ```
#[inline(always)]
#[rustc_const_unstable(feature = "const_pin", issue = "76654")]
#[stable(feature = "pin_into_inner", since = "1.39.0")]
/// that the closure is pinned.
///
/// The better alternative is to avoid all that trouble and do the pinning in the outer function
- /// instead (here using the unstable `pin` macro):
+ /// instead (here using the [`pin!`][crate::pin::pin] macro):
/// ```
- /// #![feature(pin_macro)]
/// use std::pin::pin;
/// use std::task::Context;
/// use std::future::Future;
///
/// This overwrites pinned data, but that is okay: its destructor gets
/// run before being overwritten, so no pinning guarantee is violated.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// use std::pin::Pin;
+ ///
+ /// let mut val: u8 = 5;
+ /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val);
+ /// println!("{}", pinned); // 5
+ /// pinned.as_mut().set(10);
+ /// println!("{}", pinned); // 10
+ /// ```
#[stable(feature = "pin", since = "1.33.0")]
#[inline(always)]
pub fn set(&mut self, value: P::Target)
impl<'a, T: ?Sized> Pin<&'a T> {
/// Constructs a new pin by mapping the interior value.
///
- /// For example, if you wanted to get a `Pin` of a field of something,
+ /// For example, if you wanted to get a `Pin` of a field of something,
/// you could use this to get access to that field in one line of code.
/// However, there are several gotchas with these "pinning projections";
/// see the [`pin` module] documentation for further details on that topic.
/// Construct a new pin by mapping the interior value.
///
- /// For example, if you wanted to get a `Pin` of a field of something,
+ /// For example, if you wanted to get a `Pin` of a field of something,
/// you could use this to get access to that field in one line of code.
/// However, there are several gotchas with these "pinning projections";
/// see the [`pin` module] documentation for further details on that topic.
/// ### Basic usage
///
/// ```rust
-/// #![feature(pin_macro)]
/// # use core::marker::PhantomPinned as Foo;
/// use core::pin::{pin, Pin};
///
/// ### Manually polling a `Future` (without `Unpin` bounds)
///
/// ```rust
-/// #![feature(pin_macro)]
/// use std::{
/// future::Future,
/// pin::pin,
/// ### With `Generator`s
///
/// ```rust
-/// #![feature(generators, generator_trait, pin_macro)]
+/// #![feature(generators, generator_trait)]
/// use core::{
/// ops::{Generator, GeneratorState},
/// pin::pin,
/// The following, for instance, fails to compile:
///
/// ```rust,compile_fail
-/// #![feature(pin_macro)]
/// use core::pin::{pin, Pin};
/// # use core::{marker::PhantomPinned as Foo, mem::drop as stuff};
///
/// constructor.
///
/// [`Box::pin`]: ../../std/boxed/struct.Box.html#method.pin
-#[unstable(feature = "pin_macro", issue = "93178")]
+#[stable(feature = "pin_macro", since = "CURRENT_RUSTC_VERSION")]
#[rustc_macro_transparency = "semitransparent"]
#[allow_internal_unstable(unsafe_pin_internals)]
pub macro pin($value:expr $(,)?) {
projects / rust.git / blobdiff