Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove [mut] syntax in pin docs #59900

Merged
merged 3 commits into from
Apr 14, 2019
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions src/libcore/pin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -158,28 +158,29 @@
//! 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
//! pinning with a `#[repr(packed)]` type.
//!
//! # 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<&[mut] Struct>) -> Pin<&[mut] Field>`?
//! In a similar vein, when can a generic wrapper type (such as `Vec<T>`, `Box<T>`, or `RefCell<T>`)
//! have an operation with type `fn(Pin<&[mut] Wrapper<T>>) -> Pin<&[mut] 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<T>`, `Box<T>`,
//! or `RefCell<T>`) have an operation with type `fn(Pin<&Wrapper<T>>) ->
//! Pin<&T>` (or similarly `fn(Pin<&mut Wrapper<T>>) -> Pin<&mut T>`)?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now it may be read like only the Wrapper thing also applies to mut. That's why I was a bit more vague in my suggestion.

If you think that is too vague, what about instead just being explicit: "(Whenever shared references are used in this discussion, the same applies equally to mutable 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.
//! 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:
Expand Down