AsyncBufRead Readline Semantics

[acminor]

Version

tokio 0.2.0-alpha.4

Platform

Linux localhost.localdomain 5.2.11-200.fc30.x86_64 #1 SMP Thu Aug 29 12:43:20 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux

Description

When using the AsyncBufReadExt trait to use the readline function,
I encountered something slightly counter-intuitive. Most languages that implement
this reset the buffer on new reads, but readline did not. I confirmed this by using code
similar to the following pseudo code:

let buf = String::new()
loop {
   println!("{}", buf.len())
   buf.readline(&mut buf).await {...}
}

I am unsure of Rust's standard library semantics on this, yet this seems to be counter-intuitive
as their is lingering data between each call and this must be cleared explicitly.

If this is correct semantics, is it possible to update the documentation to reflect this.
It represented it self as an interesting bug for my work as it slowed everything down
and did not break my parsing logic because my parsing logic is permissive.

[taiki-e]

This is the same behavior as std::io::BufRead::read_line (related: rust-lang/rust#23636).
The buffer needs to be cleared each time. And AsyncBufReadExt::lines may be more convenient for your use case. (the documents of tokio::io's *Ext traits does not have example code, so it is linked to the documents of futures-preview, but the implementations are basically the same.)

If this is correct semantics, is it possible to update the documentation to reflect this.

The document says "will be appended to buf", but I think it needs to add examples.

Once found, all bytes up to, and including, the delimiter (if found) will be appended to buf.

[acminor]

@taiki-e

Thanks, I did not notice the "appended to buf" sentence. Hmm, it is still a little strange that for something (at least to me) that seems counter-intuitive to how buffers are viewed that their is not a more prominent documentation point.

I will leave this open to allow a moderator to close it pending any further discussion on documentation or examples.

---

I do also agree with it fitting Rust's implementation of BufRead. However as I do not use that much, I did not know this implementation detail.