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.

Sign up for GitHub

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

Jump to bottom

Add examples for std::pin::Pin new() and into_inner() methods #104195

Closed
wants to merge 9 commits into from
Closed

Add examples for std::pin::Pin new() and into_inner() methods #104195

Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fe2f40a
Add an example for Pin::new()
ch-iv Nov 8, 2022
8b5379e
Add example for the into_inner() method
ch-iv Nov 9, 2022
dfa90e7
fix formatting
ch-iv Nov 9, 2022
fd8ebea
Merge branch 'documentation-104107' of https://github.com/ch-iv/rust …
ch-iv Nov 9, 2022
6f48b60
Repace inaccruate comment
ch-iv Nov 9, 2022
a4ee02b
formatting
ch-iv Nov 9, 2022
06c2ce0
Update library/core/src/pin.rs
ch-iv Nov 10, 2022
0b1ead3
Merge branch 'rust-lang:master' into documentation-104107
ch-iv Nov 23, 2022
7a47e2c
Demonstrate with an &mut reference
ch-iv Nov 23, 2022
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
21 changes: 21 additions & 0 deletions library/core/src/pin.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -485,6 +485,16 @@ impl<P: Deref<Target: Unpin>> Pin<P> {
///
/// 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 val: u8 = 5;
/// // Wrap the value in a pin to make sure it doesn't move
Copy link
Member

Choose a reason for hiding this comment

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

This isn't quite accurate. Since Target: Unpin, the value can move again.

Suggested change
/// // Wrap the value in a pin to make sure it doesn't move
/// // The value doesn't care about being moved, so we can pin it just fine

I don't like my wording here a lot, feel free to improve it, but something like this is better.

Copy link
Member

Choose a reason for hiding this comment

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

I guess that a better option is Pin the value in memory to make sure that during the program lifecycle the value is not moved in another memory address?

/// let pinned: Pin<&u8> = Pin::new(&val);
Copy link
Member

Choose a reason for hiding this comment

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

It seems like an example of Pin with a shared reference is probably not the best bet -- most users will not want that. I think we should demonstrate with a &mut reference at least.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

    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

Would this work?

/// ```
#[inline(always)]
#[rustc_const_unstable(feature = "const_pin", issue = "76654")]
#[stable(feature = "pin", since = "1.33.0")]
Expand All @@ -498,6 +508,17 @@ impl<P: Deref<Target: Unpin>> Pin<P> {
///
/// This requires that the data inside this `Pin` is [`Unpin`] so that we
ch-iv marked this conversation as resolved.
Show resolved Hide resolved
/// can ignore the pinning invariants when unwrapping it.
///
/// # Examples
///
/// ```
/// use std::pin::Pin;
///
/// let pinned: Pin<&u8> = Pin::new(&5);
/// // 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")]
Expand Down