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.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[joshtriplett]

@rfcbot concern name

Registering a concern so that this FCP doesn't complete until we finalize the name.

I agree that into_parts makes sense here; this is a safe method returning safe objects, unlike Vec::into_raw_parts which is unsafe and returns a raw pointer.

[joshtriplett]

@ijackson If the only thing that changes is the name, we don't need to delay stabilization (other than to wait for the PR changing the name). If something more substantive changes, we can consider if that impacts the evaluation we've done so far or not.

[m-ou-se]

The 'raw' here refers to the fact that unlike .into_inner(), this function does not attempt to flush the data but just directly gives you the 'raw' parts of the buffer, without trying to process them.

I can see how it can be confusing with our other uses of the word raw, but just calling it .into_parts() might not make clear what the difference with .into_inner() is. (Though on the other hand, one could argue that .into_inner has to consolidate the parts into a single 'inner' again before returning it, wheras .into_parts just returns the parts (the buffer and the underlying writer) directly.)

[ijackson]

into_inner gives you just an inner writer; into_parts gives you all the parts. I don't have a particularly strong feeling about this but I think into_parts is somewhat better. So I'll go and deal with the review comment on the fixups MR #85901.

[m-ou-se]

Looks like WriterPanicked isn't publicly available: https://doc.rust-lang.org/nightly/std/io/struct.BufWriter.html#method.into_raw_parts Did something go wrong there with the visibility?

[ijackson]

@m-ou-se: Yes, something did go wrong - I don't think I understood how all the use/visibility/stability plumbing worked. I was trying to fix that in #85901 but there is still something wrong with that. I will fix it tomorrow when I have a clear head. My apologies.