io: Add the Peek trait

[LinkTed]

Add the trait for each struct which has a peek function.

Motivation

This new Trait make it possible to write a generic, where a stream is required, in which the data is not removed from the queue. Unfortunately, there are already peek method for some struct for example TcpStream, which make it not consistent (dirty).

[rust-highfive]

r? @kennytm

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

[bors]

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

[JohnCSimon]

Ping from triage:
@LinkTed Can you please address the merge conflicts?
please set S-waiitng-on-review afterwards

[LinkTed]

Ping from triage:
@LinkTed Can you please address the merge conflicts?
please set S-waiitng-on-review afterwards

Okay, I will that.

[LinkTed]

@JohnCSimon

I rebased it, but it seems that I cannot change the label to S-waiitng-on-review.

[dylni]

@rustbot label: -S-waiting-on-author +S-waiting-on-review

[kennytm]

1. should this be implemented for UdpSocket?
2. can https://docs.rs/std-io-peek/0.1.0/std_io_peek/ be used instead? (This PR additionally implements for UnixStream and UnixDatagram but both are unstable under Tracking Issue for feature(unix_socket_peek) #76923; adding an unstable Peek trait isn't going to change that)

[LinkTed]

1. should this be implemented for [`UdpSocket`](https://doc.rust-lang.org/std/net/struct.UdpSocket.html#method.peek)?

I will add implement for UdpSocket too.

2. can https://docs.rs/std-io-peek/0.1.0/std_io_peek/ be used instead? (This PR additionally implements for UnixStream and UnixDatagram but both are unstable under [Tracking Issue for feature(unix_socket_peek) #76923](https://github.com/rust-lang/rust/issues/76923); adding an unstable Peek trait isn't going to change that)

Should I create a new tracking issue?

[kennytm]

@LinkTed

Should I create a new tracking issue?

What I mean is, currently stable code can't use Unix{Stream,Datagram}::peek as they are unstable. But stable code can't use this Peek trait either since it is also unstable.

If Unix{Stream,Datagram}::peek is stabilized then an external crate like std-io-peek can also do the same job. Besides, std itself does not rely on the Peek trait anywhere.

So the actual question of this is, whether the Peek trait is really needed to be frozen into std? This is where I have doubt.

[LinkTed]

@LinkTed

Should I create a new tracking issue?

What I mean is, currently stable code can't use Unix{Stream,Datagram}::peek as they are unstable. But stable code can't use this Peek trait either since it is also unstable.

I understand that, so this PR has to be merged after the stabilization.

If Unix{Stream,Datagram}::peek is stabilized then an external crate like std-io-peek can also do the same job. Besides, std itself does not rely on the Peek trait anywhere.

The reason, why it does not rely on anywhere, is that it was not there yet.

So the actual question of this is, whether the Peek trait is really needed to be frozen into std? This is where I have doubt.

With this argument, then many things should not be in std. I don't see any harm, that it would cause.

[joshtriplett]

We discussed this in today's @rust-lang/libs-api meeting. We came to consensus on two points:

• As a new trait, this should use ReadBuf, rather than using a &mut [u8] buffer that requires initialization.
• We'd like to have some details about the specific use cases for having a trait abstracting this.

[bors]

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

[LinkTed]

We discussed this in today's @rust-lang/libs-api meeting. We came to consensus on two points:

* As a new trait, this should use `ReadBuf`, rather than using a `&mut [u8]` buffer that requires initialization.

* We'd like to have some details about the specific use cases for having a trait abstracting this.

My use case is:
The user can write functions, where it takes the bytes from the stream (TcpStream, UnixStream, TlsStream) until a specific character, for example a new line, without using BufReader. To do so, he has to check if the character, he is looking for, is in the current buffer of the stream, by using peek. And then, read only until the character.

[mbartlett21]

This seems to be BufRead, except that the caller provides the buffer, not the type implementing the trait. Is that right?

[LinkTed]

No, really. It is like BufRead, where after a read line the buffer is empty.

[JohnCSimon]

Triage:
@kennytm can you please review this?

[Mark-Simulacrum]

Based on #87620 (comment), it sounds like this will need an evaluation of the use case presented in #87620 (comment) to determine if there's a desire to add the API.

Marking as waiting-on-team for that.

These days, it's probably the case that the discussion should be had on an ACP, but I'm not sure what our policy on pre-existing PRs is there.

[yaahc]

I'm not sure what our policy on pre-existing PRs is there.

I think we've been tending to ask existing PRs to go through the ACP process.

[JohnCSimon]

Triage:
@yaahc - What (if anything) should the author do to move forward with this PR?

cc: @LinkTed

[Dylan-DPC]

Closing this as it is inactive and would need an ACP