process: document how to read output from Child

[dan-da]

tokio v1.41.0
ubuntu linux 22.04

Description

Child::wait_with_output() should take &mut self instead of self. Taking self means it cannot be used in a select!(), which means there is no good way to simultaneously wait for a child processes output and a kill/cancel channel message.

stated differently, the docs for Child::kill() provide an example of using select!() with branches for Child::wait() and a oneshot channel recv(). This example works perfectly for Child::wait() but fails to compile for Child::wait_with_output().

The only way I was able to get it to work was to copy/paste the impl of Child::wait_with_output() into my own code and modify it to take &mut self instead.

See discussion #7132 with playground examples.

[Darksonn]

This function cannot be changed due to backwards compatibility.

[dan-da]

that sounds like a good reason to never change anything.

[Darksonn]

Not making changes that break existing code is absolutely fundamental to maintain a library. We can add new methods, but we cannot delete methods or change their signature.

[dan-da]

Let's reframe as a question then:

how can an application use the tokio library to await output of a child process, and simultaneously listen for a message to kill that process? The example given for Child::kill() does not read child's output, and does not compile if Child::wait_with_output() is substituted for Child::wait().

If a simple example can be created with present API, then let's add it to the Child::kill() docs, and this can be closed. Otherwise, it seems some change (or addition) to the API must be needed. no?

[Darksonn]

Reading the child's output is of course possible, and I'm happy to see such an example. Unfortunately, I don't have time to write it right now.

[dan-da]

@maminrayej thanks for the PR. very helpful example!