bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

reword unpin auto impl section

Browse source
This commit is contained in:
Gray Olson 2023-09-27 11:39:08 +02:00 • committed by Manish Goregaokar
parent 82a68171d3
commit e2e8746bb6
2 changed files with 19 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

14
library/core/src/marker.rs
View file

@ -938,13 +938,13 @@ marker_impls! {
/// mem::replace(&mut *pinned_string, "other".to_string()); /// mem::replace(&mut *pinned_string, "other".to_string());
/// ``` /// ```
/// ///
/// This trait is automatically implemented for almost every type. The compiler (and you!) is free /// This trait is automatically implemented for almost every type. The compiler is free
/// to take the conservative stance of marking types as [`Unpin`] by default. This is because if a /// to take the conservative stance of marking types as [`Unpin`] so long as all of the types that
/// type implements [`Unpin`], then it is unsound for [`unsafe`] code to assume that type is truly /// compose its fields are also [`Unpin`]. This is because if a type implements [`Unpin`], then it
/// pinned, *even* when viewed through a "pinning" pointer! It is the responsibility of the /// is unsound for that type's implementation to rely on pinning-related guarantees for soundness,
/// implementor of [`unsafe`] code that relies upon pinning for soundness to ensure that all the /// *even* when viewed through a "pinning" pointer! It is the responsibility of the implementor of
/// types it expects to be truly pinned do not implement [`Unpin`]. For more details, see the /// a type that relies upon pinning for soundness to ensure that type is *not* marked as [`Unpin`]
/// [`pin` module] docs! /// by adding [`PhantomPinned`] field. For more details, see the [`pin` module] docs.
/// ///
/// [`mem::replace`]: crate::mem::replace "mem replace" /// [`mem::replace`]: crate::mem::replace "mem replace"
/// [`Pin`]: crate::pin::Pin "Pin" /// [`Pin`]: crate::pin::Pin "Pin"

30
library/core/src/pin.rs
View file

@ -205,7 +205,7 @@
//! value which does not actually satisfy the invariants that a pinned value must satisfy, and in //! value which does not actually satisfy the invariants that a pinned value must satisfy, and in
//! this way lead undefined behavior even in (from that point) fully safe code. Similarly, using //! this way lead undefined behavior even in (from that point) fully safe code. Similarly, using
//! [`unsafe`], one may get access to a bare [`&mut T`] from a [`Pin<Ptr>`] and //! [`unsafe`], one may get access to a bare [`&mut T`] from a [`Pin<Ptr>`] and
//! juse that to invalidly *move* pinned the value out. It is the job of the user of the //! use that to invalidly *move* pinned the value out. It is the job of the user of the
//! [`unsafe`] parts of the [`Pin`] API to ensure these invariants are not violated. //! [`unsafe`] parts of the [`Pin`] API to ensure these invariants are not violated.
//! //!
//! This differs from e.g. [`UnsafeCell`] which changes the semantics of a program's compiled //! This differs from e.g. [`UnsafeCell`] which changes the semantics of a program's compiled
@ -336,24 +336,18 @@
//! unsound without being expressed through pinning, and they would then need to not //! unsound without being expressed through pinning, and they would then need to not
//! implement [`Unpin`]. //! implement [`Unpin`].
//! //!
//! The compiler (and users!) is free to take the conservative stance of marking types as [`Unpin`] //! The compiler is free to take the conservative stance of marking types as [`Unpin`] so long as
//! by default. This is because if a type implements [`Unpin`], then it is unsound for [`unsafe`] //! all of the types that compose its fields are also [`Unpin`]. This is because if a type
//! code to assume that type is truly pinned, *even* when viewed through a "pinning" pointer! It is //! implements [`Unpin`], then it is unsound for that type's implementation to rely on
//! the responsibility of *the implementor of [`unsafe`] code that relies upon pinning for //! pinning-related guarantees for soundness, *even* when viewed through a "pinning" pointer! It is
//! soundness* (you, in this case!) to ensure that all the types which that code expects to be truly //! the responsibility of the implementor of a type that relies upon pinning for soundness to
//! pinned do not implement [`Unpin`]. //! ensure that type is *not* marked as [`Unpin`] by adding [`PhantomPinned`] field. This is
//! exactly what we did with our `AddrTracker` example above. Without doing this, you *must not*
//! rely on pinning-related guarantees to apply to your type!
//! //!
//! Like other auto-traits, the compiler will automatically determine that a type implements //! If need to truly pin a value of a foreign or built-in type that implements [`Unpin`], you'll
//! [`Unpin`] if all its fields also implement [`Unpin`]. If you are building a type which consists //! need to create your own wrapper type around the [`Unpin`] type you want to pin and then
//! of only [`Unpin`] types but has an address-sensistive state and thus should not itself //! opts-out of [`Unpin`] using [`PhantomPinned`].
//! implement [`Unpin`], you must opt out of [`Unpin`] via adding a field with the
//! [`PhantomPinned`] marker type, as we did with our latest `AddrTracker` example above. Without
//! doing this, you must not rely on the pinning guarantees to apply to your type!
//!
//! If you have reason to pin a value of a type that implements [`Unpin`] such that pinning-related
//! guarantees actually are respected, you'll need to create your own wrapper type which itself
//! opts out of implementing [`Unpin`] and contains a sub-field with the [`Unpin`] type that you
//! want to pin.
//! //!
//! Exposing access to the inner field which you want to remain pinned must then be carefully //! Exposing access to the inner field which you want to remain pinned must then be carefully
//! considered as well! Remember, exposing a method that gives access to a //! considered as well! Remember, exposing a method that gives access to a