Suggestion for BufReader Documentation Improvement

[ghost]

Introduction

After we have chased down a bug in our multiprocess application, which caused messages passed between processes to get lost sometimes, I would like to suggest including a small hint in the Rust documentation of BufReader. Maybe a lint implementation for clippy also would be possible.

Background

The messages got (sometimes partly) lost, because I repeatedly created a BufReader instance on the same ChildStdout reference for every line I wanted to read off the stream. This instance got then dropped at the end of the scope. Retroperspective this was not a wise decision in my implementation and I understand that this can cause parts of stream data to get lost when the BufReader instance gets dropped.
But when implementing it I did not think of such a possibility and finding the source of this bug was quite difficult. It ended up searching the libstd source, after having found out that a crude self implementation of read_line() somehow fixed the bug. Only this brought up the idea, that the buffering of BufReader could be the cause of our issues.

Code

The issue can be reproduced by the following simple application and one file input.log with some lines of text in the execution directory. The read lines are written for comparison into output.log.

use std::fs::{File, OpenOptions};
use std::io::{prelude::*, BufReader};

fn main() -> std::io::Result<()> {
    let mut read = File::open("./input.log")?;
    let mut write = OpenOptions::new()
        .write(true)
        .truncate(true)
        .create(true)
        .open("./output.log")?;

    loop {
        let mut reader = BufReader::new(&mut read);
        let mut line = String::new();

        match reader.read_line(&mut line) {
            Ok(0) | Err(_) => break,
            Ok(_) => write!(write, "{}", line)?,
        }
    }

    Ok(())
}

Suggestion

To decrease the chance for others repeating the same mistake, I would suggest a short hint in the documentation of BufReader, that creating multiple instances on a referenced stream (especially in some sort of loop) can cause data loss.
Maybe it might even be possible to implement a clippy lint to fetch such a pitfall.

Reference

The related users topic can be found here.