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

[ch-iv]

Fixes #104107

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Mark-Simulacrum (or someone else) soon.

Please see the contribution instructions for more information.

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[Noratrieb]

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.

[vincenzopalazzo]

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?

[vincenzopalazzo]

Some others comment regarding the PR are:

• Use the Fixes https://github.com/rust-lang/rust/issues/104107 to make sure that the PR is linked with the issue
• Try to squash the commit in a single one if the commit are simple the same things

[Mark-Simulacrum]

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.

[ch-iv]

    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?

[Mark-Simulacrum]

@rustbot author

[yoshuawuyts]

cc/ @rust-lang/wg-async I ran out of time to review this before going out of office. Can others take a look at this, perhaps during the next triage? I want to make sure we don't let this slip. Thanks!

[vincenzopalazzo]

@rustbot label +A-async-await

So in this way, it is indexed by penguin our friendly triage bot 😸

[ch-iv]

@rustbot label -S-waiting-on-author +S-waiting-on-review

[Mark-Simulacrum]

r? @yoshuawuyts

[eholk]

@bors r+

[bors]

📌 Commit 7a47e2c has been approved by eholk

It is now in the queue for this repository.

[klensy]

https://rustc-dev-guide.rust-lang.org/git.html#no-merge-policy, commits should be rebased/squashed

[matthiaskrgr]

@bors r-

[vincenzopalazzo]

@ch-iv could you rebase and squash the commit in a single one? so we can get this in soon!