Does TcpStream split need to take a mutable reference?

[bjadamson]

Hi, I want to read/write to a TcpStream with a shared reference, but got stuck because TcpStream split requires a mutable access to the stream, even though calling try_write/try_read directly does not require a mutable reference.

I want to use FramedWrite/FramedRead instead of calling try_write/try_read directly as I'm only concerned with sending/receiving and the example code I have founds shows using these to send/receive.

To construct a FramedWrite/FramedRead I split the TcpStream using split() but got stuck because split() requires a mutable reference to the stream. I'm confused how come the split method requires a mutable reference, when both reading/writing do not?

Two questions I'd like to ask:

1. Is there a way to construct a FramedRead/FramedWrite from a &TcpStream?
2. Is there a reason TcpStream split requires a mutable reference to the stream? I've looked at the implementation of split and from what I can tell it doesn't matter that the stream is a mutable reference, as the WriteHalf and ReadHalf both just store shared references to the stream.

pub fn split<'a>(&'a mut self) -> (ReadHalf<'a>, WriteHalf<'a>) {
    split(self)
}

///
pub(crate) fn split(stream: &mut TcpStream) -> (ReadHalf<'_>, WriteHalf<'_>) {
    (ReadHalf(&*stream), WriteHalf(&*stream))
}

The definitions of both halves:

#[derive(Debug)]
pub struct WriteHalf<'a>(&'a TcpStream);

#[derive(Debug)]
pub struct ReadHalf<'a>(&'a TcpStream);

[Darksonn]

There is a reason behind it taking a mutable reference. Consider what happens if you try to read simultaneously from two references to the same TcpStream. Ultimately these two reads will result in both tasks calling poll_read on the same TcpStream, but all poll methods behave like the following (taken from Future::poll):

Note that on multiple calls to poll, only the Waker from the Context passed to the most recent call should be scheduled to receive a wakeup.

This poses a problem. It is not possible for both calls to poll_read to be the most recent caller simultaneously, and this means that one of them wont be woken up, which essentially means that its call to read will hang forever. Mutable references circumvent this problem since they guarantee exclusive access, thus the above cannot happen. The split method exists because there's no problem with having one thread call poll_read and another call poll_write. There's also no problem with try_read/try_write as they don't involve any wakeups.

All that said, since introducing the split methods, the TcpStream has gained methods like readable that do take &self. The reason that these methods work is that, with two callers of readable, those two callers would be calling poll on two different objects, namely the future returned by readable. Arguably the same could be done to ReadHalf, making it such that it can tell the difference between the two callers since the poll_read calls are on different ReadHalf objects, however this was not done because split was introduced way before readable was. Though I will note that doing it in this manner would make the read halfs more annoying to use as they would no longer be Unpin.

To answer your first question as well, it would be possible to construct a wrapper around &TcpStream that implements the IO traits by taking advantage of readable and writable. It would even be possible to do this in an external crate by using the same technique as PollSemaphore. That said, I would recommend trying to find a way to avoid it. An IO resource like a TcpStream should generally not be shared (beyond splitting it), and only having a &TcpStream indicates that you are trying to share it for some reason.