From 94a5c3b2b2ea51bbe079796f24912ba4d0311e95 Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Thu, 11 Apr 2019 21:21:19 -0500 Subject: [PATCH 1/3] Remove [mut] syntax in pin docs --- src/libcore/pin.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/libcore/pin.rs b/src/libcore/pin.rs index 57bd3ed12b28e..ad3e2686228c8 100644 --- a/src/libcore/pin.rs +++ b/src/libcore/pin.rs @@ -158,12 +158,12 @@ //! is called *even if your type was previously pinned*! It is as if the //! compiler automatically called `get_unchecked_mut`. //! -//! This can never cause a problem in safe code because implementing a type that relies on pinning -//! requires unsafe code, but be aware that deciding to make use of pinning -//! in your type (for example by implementing some operation on `Pin<&[mut] Self>`) -//! has consequences for your `Drop` implementation as well: if an element -//! of your type could have been pinned, you must treat Drop as implicitly taking -//! `Pin<&mut Self>`. +//! This can never cause a problem in safe code because implementing a type that +//! relies on pinning requires unsafe code, but be aware that deciding to make +//! use of pinning in your type (for example by implementing some operation on +//! `Pin<&Self>` or `Pin<&mut Self>`) has consequences for your `Drop` +//! implementation as well: if an element of your type could have been pinned, +//! you must treat Drop as implicitly taking `Pin<&mut Self>`. //! //! In particular, if your type is `#[repr(packed)]`, the compiler will automatically //! move fields around to be able to drop them. As a consequence, you cannot use @@ -173,13 +173,13 @@ //! //! One interesting question arises when considering the interaction of pinning and //! the fields of a struct. When can a struct have a "pinning projection", i.e., -//! an operation with type `fn(Pin<&[mut] Struct>) -> Pin<&[mut] Field>`? +//! an operation with type `fn(Pin<&Struct>) -> Pin<&Field>`? //! In a similar vein, when can a generic wrapper type (such as `Vec`, `Box`, or `RefCell`) -//! have an operation with type `fn(Pin<&[mut] Wrapper>) -> Pin<&[mut] T>`? +//! have an operation with type `fn(Pin<&Wrapper>) -> Pin<&T>`? //! //! Having a pinning projection for some field means that pinning is "structural": //! when the wrapper is pinned, the field must be considered pinned, too. -//! After all, the pinning projection lets us get a `Pin<&[mut] Field>`. +//! After all, the pinning projection lets us get a `Pin<&Field>`. //! //! However, structural pinning comes with a few extra requirements, so not all //! wrappers can be structural and hence not all wrappers can offer pinning projections: From e9c9d1c305488eb1125d6a10367c81a5c411039c Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Fri, 12 Apr 2019 01:29:30 -0500 Subject: [PATCH 2/3] Add comment that field projectin also works with mutable fields --- src/libcore/pin.rs | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/libcore/pin.rs b/src/libcore/pin.rs index ad3e2686228c8..e1fe0044cc480 100644 --- a/src/libcore/pin.rs +++ b/src/libcore/pin.rs @@ -171,11 +171,12 @@ //! //! # Projections and Structural Pinning //! -//! One interesting question arises when considering the interaction of pinning and -//! the fields of a struct. When can a struct have a "pinning projection", i.e., -//! an operation with type `fn(Pin<&Struct>) -> Pin<&Field>`? -//! In a similar vein, when can a generic wrapper type (such as `Vec`, `Box`, or `RefCell`) -//! have an operation with type `fn(Pin<&Wrapper>) -> Pin<&T>`? +//! One interesting question arises when considering the interaction of pinning +//! and the fields of a struct. When can a struct have a "pinning projection", +//! i.e., an operation with type `fn(Pin<&Struct>) -> Pin<&Field>`? In a +//! similar vein, when can a generic wrapper type (such as `Vec`, `Box`, +//! or `RefCell`) have an operation with type `fn(Pin<&Wrapper>) -> +//! Pin<&T>` (or similarly `fn(Pin<&mut Wrapper>) -> Pin<&mut T>`)? //! //! Having a pinning projection for some field means that pinning is "structural": //! when the wrapper is pinned, the field must be considered pinned, too. From b754b8fb8eaa580753ea3f7bc52fa221cef2a9fe Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Sat, 13 Apr 2019 15:54:57 -0500 Subject: [PATCH 3/3] Expand note on mutable references --- src/libcore/pin.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/libcore/pin.rs b/src/libcore/pin.rs index e1fe0044cc480..d1ebe5ed72adf 100644 --- a/src/libcore/pin.rs +++ b/src/libcore/pin.rs @@ -176,7 +176,10 @@ //! i.e., an operation with type `fn(Pin<&Struct>) -> Pin<&Field>`? In a //! similar vein, when can a generic wrapper type (such as `Vec`, `Box`, //! or `RefCell`) have an operation with type `fn(Pin<&Wrapper>) -> -//! Pin<&T>` (or similarly `fn(Pin<&mut Wrapper>) -> Pin<&mut T>`)? +//! Pin<&T>`? +//! +//! Note: For the entirety of this discussion, the same applies for mutable references as it +//! does for shared references. //! //! Having a pinning projection for some field means that pinning is "structural": //! when the wrapper is pinned, the field must be considered pinned, too.