Pipe i/o example in documentation is incorrect about childprocess HOT 2 CLOSED

Thanks for the feedback, @p-mongo.

While the examples were meant to be illustrative rather than exhaustive/robust, given others are likely using them with the assumption they will do the "right thing", it's worthwhile to update them. I've done so in 8e809fe, and really appreciate your input!

Wanted to address your specific points as I think they are worth discussing:

1. It does not explicitly close the read end of the pipe because this happens automatically. If you call r.autoclose? it would return true, meaning it is closed at program exit as object finalizers are executed. With that said, this code sample may be copied verbatim, so it's worth ensuring we call r.close explicitly.

2. You are slightly incorrect on the justification for this point (perhaps you phrased in a way I'm misunderstanding—if so my apologies), but your recommendation to close the write end of the pipe is correct.

   When utilizing pipes for IPC you must close the file descriptor of the write end of the pipe in the parent process. This ensures that when the (forked) child process finally closes its file descriptor for the write end of the pipe, the parent process will receive an EOF the next time it attempts to read from the read end of the pipe. If the parent process leaves its write end of the pipe open, the EOF won't be sent as there is a still a process with an open file descriptor (the parent in this case).

   You can reproduce this with the following example which will not terminate until you uncomment the w.close line:

   r, w = IO.pipe
   process = ChildProcess.build("sleep" , "1")
   process.io.stdout = w
   process.start
   
   # w.close # Uncomment this to get example to terminate
   
   thread = Thread.new do
     begin
       loop do
         print r.readpartial(16384)
       end
     rescue EOFError # Won't happen unless we call w.close
     end
   end
   
   process.wait
   thread.join

   However, it's important to note that the example will still work if we call w.close after process.wait (as the loop will eventually return EOF in that case), but your suggestion to do before the thread is created is likely better form, so we'll update to do that.

3. I'm not able to reproduce the behavior you're describing (getting the background thread to error on the IO object being closed by another thread), but I might be misunderstanding the reproduction steps. In any case, agreed that we should call thread.join to ensure the reader exits before the parent terminates, as that is necessary for the example in 2 to work.

Thanks again for the feedback. We've updated the example.

from childprocess.

👍 thank you.

from childprocess.