Stabilize Bufwriter::into_raw_parts

[ijackson]

Update 2021-08-24

The FCP for this has already completed in #80690. This was just blocked on #85901 (which changed the name), which is now merged.

Update 2021-07-24

The methods on IntoInnerError were stabilised in #87175 (thanks, @inquisitivecrystal).

Stabilisation of BufWriter::into[_raw]_parts is blocked on #85901 which fixes some missing exports and changes the name. That MR is awaiting review.

Background and discussion

These two sets of methods both relate to disassembling a BufWriter. It is most convenient to consider them together:

• Tracking Issue for BufWriter::into_parts #80690 BufWriter::into_raw_parts (docs)
• Tracking Issue for IntoInnerError::into_parts etc. (io_into_inner_error_parts) #79704 IntoInnerError::into_parts and into_error (docs)

Without at least one of these, if the underlying writer is failing, it is not possible to get all of the innards out in a useable form for error recovery, no matter how much you know about the underlying writer and what went wrong.

Strictly speaking, BufWriter::into_raw_parts is sufficient. That avoids calling BufWriter::into_inner and therefore an IntoInnerError cannot arise. It is possibly also simpler in some cases where the caller wants to take care about errors. But into_raw_parts is clumsy in simpler situations (where what's wanted is a call that does the flush before disassembly and where errors will be considered to invalidate the underlying writer).

BufWriter::into_raw_parts was merged on 2021-01-19, and the IntoInnerError disassembly methods on 2020-12-05.

Alternatives

• Stabilise only into_raw_parts. This would be sufficient, although it does leave into_inner as something of a decoy - if into_inner is used, but later a need to do error recovery arises, the maintenance programmers will have to replace into_inner with into_raw_parts, so as to avoid ending up with an intractable IntoInnerError, and reorganise the deconstruction code. Some of the pain here could be mitigated through documentation, which could explain that that this is what is needed. But it still seems rather perverse: it would be deliberately avoiding providing into_* deconstruction methods on a type which could easily have them.
• Stabilise into_raw_parts and deprecate into_inner, IntoInnerError, and never stabilise the new disassembly methods on IntoInnerError. This seems unfriendly as it makes this complicated in simple situations.
• Stabilise neither of these facilities. This means that when error recovery is needed, the programmer would need to copy BufWriter's source into their project to add it. This (the current situation on stable) is quite poor.

Open questions

None.

Resolved questions

• Would a simpler return type from into_raw_parts be better? No: BufWriter: Provide into_raw_parts #79705 (comment)

[rust-highfive]

r? @dtolnay

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

[ijackson]

@rustbot modify labels +T-libs +needs-fcp

[rustbot]

Error: Label needs-fcp can only be set by Rust team members

Please let @rust-lang/release know if you're having trouble with this bot.

[ijackson]

@rustbot modify labels +T-libs

[JohnTitor]

Triage note: FCPs are open on these issues: #80690 (comment), #79704 (comment)

[bors]

☔ The latest upstream changes (presumably #87413) made this pull request unmergeable. Please resolve the merge conflicts.

[ijackson]

This is (still) blocked on #85901. The merge conflict is due to #87175 landing (yay), and I will fix it after #85901.

[ijackson]

Uh. I did not mean to close this. I meant to update it. Here we are, rebased onto master.