Update scaladoc for Process

[daddykotex]

I fell into this trap last week. Essentially, I was running a program that looks like this:

//> using scala "3.3.0"
//> using lib "co.fs2::fs2-io:3.9.3"

import cats.effect._
import fs2._

object Main extends IOApp.Simple {
  val run = fs2.io.process
    .ProcessBuilder(
      "git",
      "show",
      "46d8140:lightweight-dynamo.json" // just a large file that exists in the git repo
    )
    .spawn[IO]
    .use { p =>
      p.exitValue *> p.stdout.through(fs2.text.utf8.decode).compile.string
    }
    .flatMap(IO.println)
}

Unfortunately for me, when the file in question (lightweight-dynamo.json in this instance) was somewhat large, my program would hang. I tracked this down to: you must drain stdout if the process you starts is writing to it. Failure to do it can cause the process to block because it's write buffer is full (because nobody reads from it). Relevant java docs.

This change in the documentation should help avoiding such issue. But I think the best thing would be to have a mechanism in place to ensure stdin is drained. I'm not sure how I would implemented this though.

[armanbilge]

Same is true of stderr.

[daddykotex]

I thought that but was not sure because the docs on the java side only mention stdin and stdout:

Because some native platforms only provide limited buffer size for standard input and output streams, failure to promptly write the input stream or read the output stream of the subprocess may cause the subprocess to block, or even deadlock.

[armanbilge]

Oh. Maybe I'm wrong actually and stderr is special. Thanks for pointing it out.

[daddykotex]

I'm not entirely sure it's special, so I've added the warning to stderr as well.

[armanbilge]

thank you!