Stabilize `box_into_pin`#97397

JohnTitor · 2022-05-25T12:50:43Z

FCP has been completed: #62370 (comment)
Also, adds notes as per #62370 (comment)
Closes #62370

rust-highfive · 2022-05-25T12:50:45Z

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 r? rust-lang/libs-api @rustbot label +T-libs-api -T-libs to request review from a libs-api team reviewer. 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

rust-highfive · 2022-05-25T12:50:47Z

r? @Mark-Simulacrum

(rust-highfive has picked a reviewer for you, use r? to override)

JohnTitor · 2022-05-25T13:07:24Z

CI failure is unrelated:

fatal: unable to access 'https://github.com/rust-lang/rust/': Failed to connect to github.com port 443: Connection timed out

library/alloc/src/boxed.rs

Mark-Simulacrum · 2022-05-27T18:37:59Z

library/alloc/src/boxed.rs

Fundamental is an unstable (and not very well known) feature, so this seems like an odd thing to document on such a potentially prominent impl/type without links or further elaboration.

I think the impl text is also wrong, it should be From<Box<T>> for Pin<T>, right?

Is this an impl that's possible to add outside std? Maybe if the T is concrete? The blanket impl definitely seems like it would be alloc-only.

I think we should say something more concrete here, like "it's not recommended that crates add such an impl, as it'll introduce ambiguity, and give an example, rather than talking about fundamental -- that would make more sense to me.

Updated the docs via 41beb30, how about?

Mark-Simulacrum · 2022-06-01T01:16:46Z

library/alloc/src/boxed.rs

Suggested change

/// # struct Foo;

/// struct Foo; // A type defined in this crate.

Mark-Simulacrum · 2022-06-01T01:18:22Z

library/alloc/src/boxed.rs

Suggested change

/// as it'll introduce ambiguity, for example:

/// as it'll introduce an ambiguity when calling `Pin::from`. A demonstration of such a poor impl is shown below.

Mark-Simulacrum · 2022-06-01T01:18:33Z

r=me with nits resolved; please squash commits

JohnTitor · 2022-06-02T03:21:07Z

@bors r=Mark-Simulacrum

bors · 2022-06-02T03:21:09Z

📌 Commit 572c390 has been approved by Mark-Simulacrum

…=Mark-Simulacrum Stabilize `box_into_pin` FCP has been completed: rust-lang#62370 (comment) Also, adds notes as per rust-lang#62370 (comment) Closes rust-lang#62370

Rollup of 6 pull requests Successful merges: - rust-lang#96894 (Apply track_caller to closure on `expect_non_local()`) - rust-lang#97023 (Diagnose anonymous lifetimes errors more uniformly between async and regular fns) - rust-lang#97397 (Stabilize `box_into_pin`) - rust-lang#97587 (Migrate more diagnostics to use the `#[derive(SessionDiagnostic)]`) - rust-lang#97603 (Arc make_mut doc comment spelling correction.) - rust-lang#97635 (Fix file metadata documentation for Windows) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

…n-docs, r=thomcc Improve documentation for constructors of pinned `Box`es Adds a cross-references between `Box::pin` and `Box::into_pin` (and other related methods, i.e. the equivalent `From` implementation, and the unstable `pin_in` method), in particular now that `into_pin` [was stabilized](rust-lang#97397). The main goal is to further improve visibility of the fact that `Box<T> -> Pin<Box<T>>` conversion exits in the first place, and that `Box::pin(x)` is – essentially – just a convenience function for `Box::into_pin(Box::new(x))` The motivating context why I think this is important is even experienced Rust users overlooking the existence this kind of conversion, [e.g. in this thread on IRLO](https://internals.rust-lang.org/t/pre-rfc-function-variants/16732/7?u=steffahn); and also the fact that that discussion brought up that there would be a bunch of Box-construction methods "missing" such as e.g. methods with fallible allocation a la "`Box::try_pin`", and similar; while those are in fact *not* necessary, because you can use `Box::into_pin(Box::try_new(x)?)` instead. I have *not* included explicit mention of methods (e.g. `try_new`) in the docs of stable methods (e.g. `into_pin`). (Referring to unstable API in stable API docs would be bad style IMO.) Stable examples I have in mind with the statement "constructing a (pinned) Box in a different way than with `Box::new`" are things like cloning a `Box`, or `Box::from_raw`. If/when `try_new` would get stabilized, it would become a very good concrete example use-case of `Box::into_pin` IMO.

…=thomcc Improve documentation for constructors of pinned `Box`es Adds a cross-references between `Box::pin` and `Box::into_pin` (and other related methods, i.e. the equivalent `From` implementation, and the unstable `pin_in` method), in particular now that `into_pin` [was stabilized](rust-lang/rust#97397). The main goal is to further improve visibility of the fact that `Box<T> -> Pin<Box<T>>` conversion exits in the first place, and that `Box::pin(x)` is – essentially – just a convenience function for `Box::into_pin(Box::new(x))` The motivating context why I think this is important is even experienced Rust users overlooking the existence this kind of conversion, [e.g. in this thread on IRLO](https://internals.rust-lang.org/t/pre-rfc-function-variants/16732/7?u=steffahn); and also the fact that that discussion brought up that there would be a bunch of Box-construction methods "missing" such as e.g. methods with fallible allocation a la "`Box::try_pin`", and similar; while those are in fact *not* necessary, because you can use `Box::into_pin(Box::try_new(x)?)` instead. I have *not* included explicit mention of methods (e.g. `try_new`) in the docs of stable methods (e.g. `into_pin`). (Referring to unstable API in stable API docs would be bad style IMO.) Stable examples I have in mind with the statement "constructing a (pinned) Box in a different way than with `Box::new`" are things like cloning a `Box`, or `Box::from_raw`. If/when `try_new` would get stabilized, it would become a very good concrete example use-case of `Box::into_pin` IMO.

rust-highfive assigned Mark-Simulacrum May 25, 2022

rustbot added the T-libs Relevant to the library team, which will review and decide on the PR/issue. label May 25, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 25, 2022

wwylele reviewed May 25, 2022

View reviewed changes

library/alloc/src/boxed.rs Outdated Show resolved Hide resolved

JohnTitor force-pushed the stabilize-box-into-pin branch from 3e6fe5f to 0a05584 Compare May 25, 2022 13:26

Mark-Simulacrum reviewed May 27, 2022

View reviewed changes

Mark-Simulacrum reviewed Jun 1, 2022

View reviewed changes

library/alloc/src/boxed.rs Outdated

Copy link

Member

Mark-Simulacrum Jun 1, 2022

Choose a reason for hiding this comment

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

Suggested change

/// # struct Foo;

/// struct Foo; // A type defined in this crate.

Mark-Simulacrum reviewed Jun 1, 2022

View reviewed changes

Mark-Simulacrum added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 1, 2022

Stabilize box_into_pin

572c390

JohnTitor force-pushed the stabilize-box-into-pin branch from 9b04af3 to 572c390 Compare June 1, 2022 22:24

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jun 2, 2022

Dylan-DPC mentioned this pull request Jun 2, 2022

Rollup of 5 pull requests #97637

Closed

Dylan-DPC mentioned this pull request Jun 2, 2022

Rollup of 6 pull requests #97644

Merged

bors merged commit 9225f78 into rust-lang:master Jun 2, 2022

rustbot added this to the 1.63.0 milestone Jun 2, 2022

steffahn mentioned this pull request Jun 2, 2022

Improve documentation for constructors of pinned Boxes #97655

Merged

JohnTitor deleted the stabilize-box-into-pin branch June 2, 2022 22:03

JohnTitor added the relnotes Marks issues that should be documented in the release notes of the next release. label Jun 21, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

Stabilize `box_into_pin`#97397