net: add support for anonymous unix pipes

[satakuma]

Motivation

Allow users to work with anonymous Unix pipes in Tokio, i.e.:

• create a new, nonblocking, anonymous pipe with a specialized function in tokio::net::unix::pipe
• use Tokio types from tokio::net::unix::pipe with pipes created in other ways, such as manual pipe() syscalls.

Closes: #5547

Solution

1. Add the tokio::net::unix::pipe::new() function, which creates an anonymous pipe. This function delegates creation of a pipe to Mio, which in turn performs either pipe() or pipe2() syscall.
2. Add functions to do conversion from and into OwnedFd for pipe::Sender and pipe::Receiver structs. Each of the structs gets the following new methods:

• fn into_owned_fd(self) -> io::Result<OwnedFd>
• fn from_owned_fd(owned_fd: OwnedFd) -> io::Result<Sender>
• fn from_owned_fd_unchecked(owned_fd: OwnedFd) -> io::Result<Sender>

into_owned_fd will put the pipe end into blocking mode to prevent errors in case when the file descriptor is later passed as Stdio to a child process, which usually expects a blocking stdio. This behavior is also consistent with into_owned_fd for pipes used in tokio::process.

Similarly to from_file, from_owned_fd checks if the provided file descriptor:

1. is a pipe,
2. has relevant read or write access,
3. is in non-blocking mode and if it isn't, then sets the O_NONBLOCK flag.

from_owned_fd_unchecked does none of these checks. I opted for adding both checked and unchecked variants for conversion from a file descriptor, since those types already have from_file and from_file_unchecked methods, which have similar semantics. However, this solution is a little bloated, so I am open to other ideas.

[Darksonn]

I don't understand this sentence. Are you saying that if they want to do this, they should read the source code of tokio::process to figure out how?

[satakuma]

I would like to encourage users to first see if using a combination like Command::stdout(Stdio::piped()) and ChildStdout is enough for their use case of anonymous pipes when spawning a process. This interface has been in tokio and the standard library for ages, and is arguably easier to use than tokio::net::unix::pipe, although it's obviously limited to stdin/stdout/stderr. However this module will be the first to show up if a user tries to search "pipe" in tokio's docs.

In the module level documentation of tokio::process there are examples using Stdio::piped(), but I don't know how to directly link to them.

[Darksonn]

I'd prefer to call this something else. We have similar methods for various message passing channels, and there the method is called "channel".

Suggested change

	pub fn new() -> io::Result<(Sender, Receiver)> {
	pub fn pipe() -> io::Result<(Sender, Receiver)> {

[satakuma]

I agree, pipe sounds more reasonable.

[Darksonn]

What happens if set_blocking fails? Is the fd closed?

[satakuma]

The file descriptor gets closed once mio_pipe is dropped.

[Darksonn]

I don't think this should set the fd into blocking mode.

[satakuma]

On the one hand, all other methods in net such as TcpStream::into_std do not change the non-blocking mode. On the other hand, ChildStdio, which also represents a pipe on unix, does set the fd into blocking mode. One argument I can see behind doing so is the following example from one of the tests:

tokio/tokio/tests/net_unix_pipe.rs

Lines 465 to 471 in 58b0a11

	let (tx, mut rx) = pipe::new()?;
	let status = Command::new("echo")
	.arg("-n")
	.arg(DATA)
	.stdout(tx.into_owned_fd()?)
	.status();

Usually, the spawned process will expect a blocking stdio, and in my opinion, it's easy to forget about setting the blocking mode manually. Let me know what you think.

[satakuma]

As a side note, we should document the fact that ChildStdout::into_owned_fd and others set the blocking mode.

[Darksonn]

Perhaps split into two methods: into_blocking_fd, into_nonblocking_fd.

[satakuma]

I've addressed your review comments and divided into_owned_fd into two methods. Please take another look @Darksonn.

[Darksonn]

Only one nit, otherwise LGTM.