From 6e882790b89080e337fa8ff8541023f3b1984c0f Mon Sep 17 00:00:00 2001 From: Gray Olson Date: Tue, 3 Oct 2023 09:29:02 +0200 Subject: [PATCH] `Pin

` -> `Pin` --- library/core/src/pin.rs | 156 +++++++++++++++++++++------------------- 1 file changed, 81 insertions(+), 75 deletions(-) diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index bb315949d8bcc..70c6ddc2a9887 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -273,7 +273,7 @@ //! order to identify the type of the pinned pointee data and provide (restricted) access to it. //! //! A [`Pin`] where [`Ptr: Deref`][Deref] is a "`Ptr`-style pinning pointer" to a pinned -//! [`P::Target`][Target] – so, a [Pin]<[Box]\> is an owned, pinning pointer to a +//! [`Ptr::Target`][Target] – so, a [Pin]<[Box]\> is an owned, pinning pointer to a //! pinned `T`, and a [Pin]<[Rc]\> is a reference-counted, pinning pointer to a //! pinned `T`. //! @@ -590,7 +590,7 @@ //! # Implementing an address-sensitive type. //! //! This section goes into detail on important considerations for implementing your own -//! address-sensitive types, which are different from merely using [`Pin

`] in a generic +//! address-sensitive types, which are different from merely using [`Pin`] in a generic //! way. //! //! ## Implementing [`Drop`] for types with address-sensitive states @@ -689,7 +689,7 @@ //! Even though we can't have the compiler do the assignment for us, it's possible to write //! such specialized functions for types that might need it. //! -//! Note that it _is_ possible to assign generically through a [`Pin

`] by way of [`Pin::set()`]. +//! Note that it _is_ possible to assign generically through a [`Pin`] by way of [`Pin::set()`]. //! This does not violate any guarantees, since it will run [`drop`] on the pointee value before //! assigning the new value. Thus, the [`drop`] implementation still has a chance to perform the //! necessary notifications to dependent values before the memory location of the original pinned @@ -1050,7 +1050,7 @@ use crate::{ #[fundamental] #[repr(transparent)] #[derive(Copy, Clone)] -pub struct Pin

{ +pub struct Pin { // FIXME(#93176): this field is made `#[unstable] #[doc(hidden)] pub` to: // - deter downstream users from accessing it (which would be unsound!), // - let the `pin!` macro access it (such a macro requires using struct @@ -1058,7 +1058,7 @@ pub struct Pin

{ // Long-term, `unsafe` fields or macro hygiene are expected to offer more robust alternatives. #[unstable(feature = "unsafe_pin_internals", issue = "none")] #[doc(hidden)] - pub pointer: P, + pub pointer: Ptr, } // The following implementations aren't derived in order to avoid soundness @@ -1068,68 +1068,68 @@ pub struct Pin

{ // See for more details. #[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl PartialEq> for Pin

+impl PartialEq> for Pin where - P::Target: PartialEq, + Ptr::Target: PartialEq, { fn eq(&self, other: &Pin) -> bool { - P::Target::eq(self, other) + Ptr::Target::eq(self, other) } fn ne(&self, other: &Pin) -> bool { - P::Target::ne(self, other) + Ptr::Target::ne(self, other) } } #[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl> Eq for Pin

{} +impl> Eq for Pin {} #[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl PartialOrd> for Pin

+impl PartialOrd> for Pin where - P::Target: PartialOrd, + Ptr::Target: PartialOrd, { fn partial_cmp(&self, other: &Pin) -> Option { - P::Target::partial_cmp(self, other) + Ptr::Target::partial_cmp(self, other) } fn lt(&self, other: &Pin) -> bool { - P::Target::lt(self, other) + Ptr::Target::lt(self, other) } fn le(&self, other: &Pin) -> bool { - P::Target::le(self, other) + Ptr::Target::le(self, other) } fn gt(&self, other: &Pin) -> bool { - P::Target::gt(self, other) + Ptr::Target::gt(self, other) } fn ge(&self, other: &Pin) -> bool { - P::Target::ge(self, other) + Ptr::Target::ge(self, other) } } #[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl> Ord for Pin

{ +impl> Ord for Pin { fn cmp(&self, other: &Self) -> cmp::Ordering { - P::Target::cmp(self, other) + Ptr::Target::cmp(self, other) } } #[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl> Hash for Pin

{ +impl> Hash for Pin { fn hash(&self, state: &mut H) { - P::Target::hash(self, state); + Ptr::Target::hash(self, state); } } -impl> Pin

{ - /// Construct a new `Pin

` around a pointer to some data of a type that +impl> Pin { + /// Construct a new `Pin` around a pointer to some data of a type that /// implements [`Unpin`]. /// /// Unlike `Pin::new_unchecked`, this method is safe because the pointer - /// `P` dereferences to an [`Unpin`] type, which cancels the pinning guarantees. + /// `Ptr` dereferences to an [`Unpin`] type, which cancels the pinning guarantees. /// /// # Examples /// @@ -1143,16 +1143,16 @@ impl> Pin

{ #[inline(always)] #[rustc_const_unstable(feature = "const_pin", issue = "76654")] #[stable(feature = "pin", since = "1.33.0")] - pub const fn new(pointer: P) -> Pin

{ + pub const fn new(pointer: Ptr) -> Pin { // SAFETY: the value pointed to is `Unpin`, and so has no requirements // around pinning. unsafe { Pin::new_unchecked(pointer) } } - /// Unwraps this `Pin

` returning the underlying pointer. + /// Unwraps this `Pin`, returning the underlying pointer. /// - /// This requires that the data inside this `Pin` implements [`Unpin`] so that we - /// can ignore the pinning invariants when unwrapping it. + /// Doing this operation safely requires that the data pointed at by this pinning pointer + /// implemts [`Unpin`] so that we can ignore the pinning invariants when unwrapping it. /// /// # Examples /// @@ -1168,13 +1168,13 @@ impl> Pin

{ #[inline(always)] #[rustc_const_unstable(feature = "const_pin", issue = "76654")] #[stable(feature = "pin_into_inner", since = "1.39.0")] - pub const fn into_inner(pin: Pin

) -> P { + pub const fn into_inner(pin: Pin) -> Ptr { pin.pointer } } -impl Pin

{ - /// Construct a new `Pin

` around a reference to some data of a type that +impl Pin { + /// Construct a new `Pin` around a reference to some data of a type that /// may or may not implement `Unpin`. /// /// If `pointer` dereferences to an `Unpin` type, `Pin::new` should be used @@ -1184,18 +1184,18 @@ impl Pin

{ /// /// This constructor is unsafe because we cannot guarantee that the data /// pointed to by `pointer` is pinned, meaning that the data will not be moved or - /// its storage invalidated until it gets dropped. If the constructed `Pin

` does - /// not guarantee that the data `P` points to is pinned, that is a violation of + /// its storage invalidated until it gets dropped. If the constructed `Pin` does + /// not guarantee that the data `Ptr` points to is pinned, that is a violation of /// the API contract and may lead to undefined behavior in later (safe) operations. /// - /// By using this method, you are making a promise about the `P::Deref` and - /// `P::DerefMut` implementations, if they exist. Most importantly, they + /// By using this method, you are making a promise about the `Ptr::Deref` and + /// `Ptr::DerefMut` implementations, if they exist. Most importantly, they /// must not move out of their `self` arguments: `Pin::as_mut` and `Pin::as_ref` - /// will call `DerefMut::deref_mut` and `Deref::deref` *on the pointer type P* + /// will call `DerefMut::deref_mut` and `Deref::deref` *on the pointer type `Ptr`* /// and expect these methods to uphold the pinning invariants. - /// Moreover, by calling this method you promise that the reference `P` + /// Moreover, by calling this method you promise that the reference `Ptr` /// dereferences to will not be moved out of again; in particular, it - /// must not be possible to obtain a `&mut P::Target` and then + /// must not be possible to obtain a `&mut Ptr::Target` and then /// move out of that reference (using, for example [`mem::swap`]). /// /// For example, calling `Pin::new_unchecked` on an `&'a mut T` is unsafe because @@ -1299,7 +1299,7 @@ impl Pin

{ #[inline(always)] #[rustc_const_unstable(feature = "const_pin", issue = "76654")] #[stable(feature = "pin", since = "1.33.0")] - pub const unsafe fn new_unchecked(pointer: P) -> Pin

{ + pub const unsafe fn new_unchecked(pointer: Ptr) -> Pin { Pin { pointer } } @@ -1312,34 +1312,39 @@ impl Pin

{ /// ruled out by the contract of `Pin::new_unchecked`. #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] - pub fn as_ref(&self) -> Pin<&P::Target> { + pub fn as_ref(&self) -> Pin<&Ptr::Target> { // SAFETY: see documentation on this function unsafe { Pin::new_unchecked(&*self.pointer) } } - /// Unwraps this `Pin

` returning the underlying pointer. + /// Unwraps this `Pin` returning the underlying pointer. /// /// # Safety /// /// This function is unsafe. You must guarantee that you will continue to - /// treat the pointer `P` as pinned after you call this function, so that + /// treat the pointer `Ptr` as pinned after you call this function, so that /// the invariants on the `Pin` type can be upheld. If the code using the - /// resulting `P` does not continue to maintain the pinning invariants that + /// resulting `Ptr` does not continue to maintain the pinning invariants that /// is a violation of the API contract and may lead to undefined behavior in /// later (safe) operations. /// + /// Note that you must be able to guarantee that the data pointed to by `Ptr` + /// will be treated as pinned all the way until its `drop` handler is complete! + /// + /// *For more information, see the [`pin` module docs][self]* + /// /// If the underlying data is [`Unpin`], [`Pin::into_inner`] should be used /// instead. #[inline(always)] #[rustc_const_unstable(feature = "const_pin", issue = "76654")] #[stable(feature = "pin_into_inner", since = "1.39.0")] - pub const unsafe fn into_inner_unchecked(pin: Pin

) -> P { + pub const unsafe fn into_inner_unchecked(pin: Pin) -> Ptr { pin.pointer } } -impl Pin

{ - /// Gets a mutable reference to the pinned value this `Pin

` points to. +impl Pin { + /// Gets a mutable reference to the pinned value this `Pin` points to. /// /// This is a generic method to go from `&mut Pin>` to `Pin<&mut T>`. /// It is safe because, as part of the contract of `Pin::new_unchecked`, @@ -1370,12 +1375,12 @@ impl Pin

{ /// ``` #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] - pub fn as_mut(&mut self) -> Pin<&mut P::Target> { + pub fn as_mut(&mut self) -> Pin<&mut Ptr::Target> { // SAFETY: see documentation on this function unsafe { Pin::new_unchecked(&mut *self.pointer) } } - /// Assigns a new value to the memory location pointed to by the `Pin

`. + /// Assigns a new value to the memory location pointed to by the `Pin`. /// /// This overwrites pinned data, but that is okay: the original pinned value's destructor gets /// run before being overwritten and the new value is also a valid value of the same type, so @@ -1397,9 +1402,9 @@ impl Pin

{ /// [subtle-details]: self#subtle-details-and-the-drop-guarantee #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] - pub fn set(&mut self, value: P::Target) + pub fn set(&mut self, value: Ptr::Target) where - P::Target: Sized, + Ptr::Target: Sized, { *(self.pointer) = value; } @@ -1555,41 +1560,42 @@ impl Pin<&'static T> { } } -impl<'a, P: DerefMut> Pin<&'a mut Pin

> { +impl<'a, Ptr: DerefMut> Pin<&'a mut Pin> { /// 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>>` to `Pin<&mut T>`. It is /// safe because the existence of a `Pin>` ensures that the pointee, `T`, cannot /// move in the future, and this method does not enable the pointee to move. "Malicious" - /// implementations of `P::DerefMut` are likewise ruled out by the contract of + /// implementations of `Ptr::DerefMut` are likewise ruled out by the contract of /// `Pin::new_unchecked`. #[unstable(feature = "pin_deref_mut", issue = "86918")] #[must_use = "`self` will be dropped if the result is not used"] #[inline(always)] - pub fn as_deref_mut(self) -> Pin<&'a mut P::Target> { + pub fn as_deref_mut(self) -> Pin<&'a mut Ptr::Target> { // SAFETY: What we're asserting here is that going from // - // Pin<&mut Pin

> + // Pin<&mut Pin> // // to // - // Pin<&mut P::Target> + // Pin<&mut Ptr::Target> // // is safe. // // We need to ensure that two things hold for that to be the case: // - // 1) Once we give out a `Pin<&mut P::Target>`, an `&mut P::Target` will not be given out. - // 2) By giving out a `Pin<&mut P::Target>`, we do not risk of violating `Pin<&mut Pin

>` + // 1) Once we give out a `Pin<&mut Ptr::Target>`, an `&mut Ptr::Target` will not be given out. + // 2) By giving out a `Pin<&mut Ptr::Target>`, we do not risk of violating + // `Pin<&mut Pin>` // - // The existence of `Pin

` is sufficient to guarantee #1: since we already have a - // `Pin

`, it must already uphold the pinning guarantees, which must mean that - // `Pin<&mut P::Target>` does as well, since `Pin::as_mut` is safe. We do not have to rely - // on the fact that P is _also_ pinned. + // The existence of `Pin` is sufficient to guarantee #1: since we already have a + // `Pin`, it must already uphold the pinning guarantees, which must mean that + // `Pin<&mut Ptr::Target>` does as well, since `Pin::as_mut` is safe. We do not have to rely + // on the fact that `Ptr` is _also_ pinned. // - // For #2, we need to ensure that code given a `Pin<&mut P::Target>` cannot cause the - // `Pin

` to move? That is not possible, since `Pin<&mut P::Target>` no longer retains - // any access to the `P` itself, much less the `Pin

`. + // For #2, we need to ensure that code given a `Pin<&mut Ptr::Target>` cannot cause the + // `Pin` to move? That is not possible, since `Pin<&mut Ptr::Target>` no longer retains + // any access to the `Ptr` itself, much less the `Pin`. unsafe { self.get_unchecked_mut() }.as_mut() } } @@ -1609,39 +1615,39 @@ impl Pin<&'static mut T> { } #[stable(feature = "pin", since = "1.33.0")] -impl Deref for Pin

{ - type Target = P::Target; - fn deref(&self) -> &P::Target { +impl Deref for Pin { + type Target = Ptr::Target; + fn deref(&self) -> &Ptr::Target { Pin::get_ref(Pin::as_ref(self)) } } #[stable(feature = "pin", since = "1.33.0")] -impl> DerefMut for Pin

{ - fn deref_mut(&mut self) -> &mut P::Target { +impl> DerefMut for Pin { + fn deref_mut(&mut self) -> &mut Ptr::Target { Pin::get_mut(Pin::as_mut(self)) } } #[unstable(feature = "receiver_trait", issue = "none")] -impl Receiver for Pin

{} +impl Receiver for Pin {} #[stable(feature = "pin", since = "1.33.0")] -impl fmt::Debug for Pin

{ +impl fmt::Debug for Pin { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fmt::Debug::fmt(&self.pointer, f) } } #[stable(feature = "pin", since = "1.33.0")] -impl fmt::Display for Pin

{ +impl fmt::Display for Pin { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fmt::Display::fmt(&self.pointer, f) } } #[stable(feature = "pin", since = "1.33.0")] -impl fmt::Pointer for Pin

{ +impl fmt::Pointer for Pin { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fmt::Pointer::fmt(&self.pointer, f) } @@ -1653,10 +1659,10 @@ impl fmt::Pointer for Pin

{ // for other reasons, though, so we just need to take care not to allow such // impls to land in std. #[stable(feature = "pin", since = "1.33.0")] -impl CoerceUnsized> for Pin

where P: CoerceUnsized {} +impl CoerceUnsized> for Pin where Ptr: CoerceUnsized {} #[stable(feature = "pin", since = "1.33.0")] -impl DispatchFromDyn> for Pin

where P: DispatchFromDyn {} +impl DispatchFromDyn> for Pin where Ptr: DispatchFromDyn {} /// Constructs a [Pin]<[&mut] T>, by pinning a `value: T` locally. ///