Add SimplexStream structure

[wutchzone]

I think that it is unfortunate that the underlying structure backing the DuplexStream is not exposed. There are cases where a single direction will suffice, for example, when I have only a single writer and single reader, thus not requiring bidirectionality.

In this patch, I renamed the Pipe to the SimplexStream for coherence with the already existing DuplexStream and made it public

[Darksonn]

Adding a stream with one direction of communication seems reasonable, but I don't love the name SimplexStream. Maybe it's the best option, but can we come up with anything else? I guess there's the option of just keeping Pipe ...

[wutchzone]

My reasoning for not using Pipe is that it is already an overloaded term used for OS primitive, and someone could get confused by reusing it again. And since we have the DuplexStream I think™ that a better name is SimplexStream because these two structures are somewhat related.

But if you think it is negligible I will change it back to the Pipe.

[robgjansen]

A SimplexStream would be very useful and something I'm missing! You can split a TcpStream into read and write halves, so for testing I'd like to replace those with SimplexStreams. I also wonder if we might want to be able to split or into_split a DuplexStream into two SimplexStreamss?

[Darksonn]

Sorry, this PR has gotten lost. I'm happy to take it up again if you're still interested.

[wutchzone]

I would be glad to continue working on this feature (and possibly extending it into other structures, as @ robgjansen mentioned) . However, I am still uncertain whether we agree to name it SimplexStream or keep the original Pipe.

[Darksonn]

We can go with SimplexStream. Sorry for not replying earlier.

[Darksonn]

This provides a single object that is both the reader and writer, but in practice I think people will want those to be two different objects.

[robgjansen]

I agree with the previous comment. In my case I would like to use these stream objects as drop-in replacements for TcpStream and related types.

A TcpStream is specific to one "node", i.e., the client has a TcpStream, and the server has a TcpStream. For testing code that uses a TcpStream, we can replace with DuplexStreams

let (client_rw, server_rw) = tokio::io::duplex(65_536);

Here we have both the client-side and server-side objects, and both are Read+Write. Thus, code written to generically handle IO on a TcpStream will function identically when replaced with the DuplexStream.

Now in my use case, each TcpStream is split into a reader (OwnedReadHalf) and a writer (OwnedWriteHalf),

let (read_half, write_half) = tcp_stream.into_split();

and my code operates generically on the Read and on the Write objects. To replicate that, I would need the SimplexStream to work similarly:

let (client_read_half, server_write_half) = tokio::io::simplex(65_536);

And then you could stack two of these together to get functionality similar to the split of a TcpStream

let (client_read_half, server_write_half) = tokio::io::simplex(65_536);
let (server_read_half, client_write_half) = tokio::io::simplex(65_536);

Then I could pass client_read_half / client_write_half to my client-side code, and server_read_half / server_write_half to my server-side code.

There is a bit of a question about the API. Do we want tokio::io::simplex to return a SimplexStream that is Read+Write, and then support SimplexStream::into_split that returns a SimplexStreamReadHalf and SimplexStreamWriteHalf? Or should tokio::io::simplex directly return the tuple (SimplexStreamReadHalf, SimplexStreamWriteHalf) as in my examples above?

(Also, I'm not sure if it makes sense to mix DuplexStreams and SimplexStreams or not, it sorta depends on how the simplex API looks.)

[wutchzone]

IMO, we should not reinvent the wheel and try to reuse already existing APIs and facilities. It is true that for most of the use cases, we should rather return a pair of reader and writer instead of a single structure, that is a great point. Also, most of the channel-like structures already do this.
Furthermore, since SimplexStream already implements AsyncRead and AsyncWrite, we can use already existing split(…) to create reader and writer half (where possibly the split reader and writer half can be unsplit).

What do you think of it now?

[wutchzone]

I am not sure whether it makes sense to add more tests to test the SimplexStream because DuplexStream (which already uses SimplexStream) has an extensive test suite.

[Darksonn]

I think returning an already split SimplexStream makes sense as an API.

[Darksonn]

We could make new public, but then I'd call it new_unsplit or similar.

[Darksonn]

Overall LGTM. Just one more minor request below.

[Darksonn]

I think it would be nice to include a link to the simplex function that acts as the primary constructor.

Currently it looks like this: https://deploy-preview-6589--tokio-rs.netlify.app/tokio/io/struct.simplexstream

[wutchzone]

I extended the documentation with links & rebased the PR.

[Darksonn]

Thanks!

[Darksonn]

Everything on the first markdown line is visible in the module docs.

Please move everything after the first period into a new paragraph.

Suggested change

	/// A unidirectional pipe to read and write bytes in memory. It can be constructed
	/// by [`simplex`] function which will create a pair of reader and writer or by
	/// calling [`SimplexStream::new_unsplit`] that will create a handle for both
	/// reading and writing.
	/// A unidirectional pipe to read and write bytes in memory.
	///
	/// It can be constructed by [`simplex`] function which will create a pair of
	/// reader and writer or by calling [`SimplexStream::new_unsplit`] that will
	/// create a handle for both reading and writing.

[wutchzone]

Ops, should be fixed.

[Darksonn]

Thanks!