Tracking Issue for BufWriter::into_parts

[ijackson]

Feature gate: #![feature(bufwriter_into_parts)]

This is a tracking issue for BufWriter::into_parts and its associated error type etc.

This allows a BufWriter to be disassembled, and the inner writer to be recovered - without attempting to write out any buffered data (instead it is returnedt to the caller), and therefore (unlike into_inner) succeeding even if the underlying writer is returning errors.

Public API

// std::io

/// Disassembles this `BufWriter<W>`, returning the underlying writer, and any buffered but
/// unwritten data.
impl<W> BufWriter<W> {
    pub fn into_parts(mut self) -> (W, Result<Vec<u8>, WriterPanicked>);
}

/// Error newtype, wraps the buffered data, a `Vec<u8>`
pub struct WriterPanicked {...}

impl WriterPanicked {
    pub fn into_inner(self) -> Vec<u8>;
}

impl Error for WriterPanicked {...}
impl Display for WriterPanicked {...}
impl Debug for WriterPanicked {...}

Steps / History

• Implementation: BufWriter: Provide into_raw_parts #79705
• Gain experience with this API, to see if it's good
• Stabilization PR with Final commenting period (FCP)

Unresolved Questions

• Should into_raw_parts be called into_parts? Tracking Issue for BufWriter::into_parts #80690 (comment)
• Is there a suitable simpler API for presenting this functionality? (I think not, see BufWriter: Provide into_raw_parts #79705 (comment))

[dtolnay]

@rust-lang/libs
@rfcbot fcp merge

Check out @ijackson's recap of this API in #84770 (comment).

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @sfackler
• @yaahc

Concerns:

• name (Tracking Issue for BufWriter::into_parts #80690 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[BurntSushi]

Should BufWriter::into_raw_parts be called into_parts instead? In all previous uses of "raw" in similar names, I believe a raw pointer is involved somewhere. But that isn't the case here.

Also, it looks like the WriterPanicked error might not actually be exported? At least, rustdoc doesn't think so: https://doc.rust-lang.org/std/io/struct.BufWriter.html#method.into_raw_parts

[ijackson]

Should BufWriter::into_raw_parts be called into_parts instead? In all previous uses of "raw" in similar names, I believe a raw pointer is involved somewhere. But that isn't the case here.

I don't have an opinion about this. I just chose that name to distinguish it more from into_inner. I would be quite happy to change it to into_parts.

Also, it looks like the WriterPanicked error might not actually be exported? At least, rustdoc doesn't think so: https://doc.rust-lang.org/std/io/struct.BufWriter.html#method.into_raw_parts

I will check this. Thanks!

[yaahc]

Should BufWriter::into_raw_parts be called into_parts instead? In all previous uses of "raw" in similar names, I believe a raw pointer is involved somewhere. But that isn't the case here.

I'm with @BurntSushi on this one, the raw in this fn name feels odd.

[ijackson]

I'm with @BurntSushi on this one, the raw in this fn name feels odd.

Indeed. I did some looking around and I think your feeling is justified:ad88a43

Hence #85901 where I change this. That ought to go first. I'm not sure what the implications are for the stabilisation - does that mean it should wait some more?

Thanks.