Add an option for starting a detached process with stdio connected

sdk/lib/io/process.dart

 // Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 // TODO(ager): The only reason for this class is that we
 // cannot patch a top-level at this point.
 class _ProcessUtils {
   external static void _exit(int status);
@@ skipping 82 matching lines @@
   }
   _ProcessUtils._sleep(milliseconds);
 }
 
 /**
  * Returns the PID of the current process.
  */
 int get pid => _ProcessUtils._pid(null);
 
 /**
+ * Modes for running a new process.
+ */
+enum ProcessStartMode {
+  /// Normal child process.
+  NORMAL,
+  /// Detached child process.
+  DETACHED,
+  /// Detachad clild process with stdin, stdout and stderr connected.

[Lasse Reichstein Nielsen, 2015/01/30 12:11:37]

clild -> child
Connected to what?

[Søren Gjesse, 2015/02/02 13:56:44]

Done.

+  DETACHED_WITH_STDIO
+}
+
+/**
  * The means to execute a program.
  *
  * Use the static [start] and [run] methods to start a new process.
  * The run method executes the process non-interactively to completion.
  * In contrast, the start method allows your code to interact with the
  * running process.
  *
  * ## Start a process with the run method
  *
  * The following code sample uses the run method to create a process
@@ skipping 128 matching lines @@
    * include the parent process's environment, with [environment] taking
    * precedence. Default is `true`.
    *
    * If [runInShell] is `true`, the process will be spawned through a system
    * shell. On Linux and Mac OS, [:/bin/sh:] is used, while
    * [:%WINDIR%\system32\cmd.exe:] is used on Windows.
    *
    * Users must read all data coming on the [stdout] and [stderr]
    * streams of processes started with [:Process.start:]. If the user
    * does not read all data on the streams the underlying system
    * resources will not be freed since there is still pending data.

[Lasse Reichstein Nielsen, 2015/01/30 12:11:37]

freed -> released

[Søren Gjesse, 2015/02/02 13:56:44]

Done.

    *
    * The following code uses `Process.start` to grep for `main` in the
    * file `test.dart` on Linux.
    *
    *     Process.start('grep', ['-i', 'main', 'test.dart']).then((process) {
    *       stdout.addStream(process.stdout);
    *       stderr.addStream(process.stderr);
    *     });
    *
-   * If [detach] is `true` a detached process will be created. A
-   * detached process has no connection to its parent, and can
-   * keep running on its own when the parent dies. The only
+   * If [mode] is [ProcessStartMode.NORMAL] a normal child process
+   * will be started.

[Lasse Reichstein Nielsen, 2015/01/30 12:11:37]

Explain what "normal" means, or rephrase as:

If [mode] is not [ProcessStartMode.NORMAL], some features of [Process] may be
unavailable.

... then the following explains which features are missing for the other modes.

[Søren Gjesse, 2015/02/02 13:56:44]

Done.

+   *
+   * If `mode` is [ProcessStartMode.DETACHED] a detached process will
+   * be created. A detached process has no connection to its parent,
+   * and can keep running on its own when the parent dies. The only
    * information available from a detached process is its `pid`. There
-   * is no connection to its `stdin`, `stdout` or `stderr` nor will its
-   * exit code become available when it terminates.
+   * is no connection to its `stdin`, `stdout` or `stderr` nor will

[Lasse Reichstein Nielsen, 2015/01/30 12:11:37]

comma before "nor"?

[Søren Gjesse, 2015/02/02 13:56:44]

Done.

+   * its exit code become available when it terminates.
+   *
+   * If `mode` is [ProcessStartMode.DETACHED_WITH_STDIO] a detached
+   * process will be created where the `stdin`, `stdout` and `stderr`
+   * are connected. The creator can communication with the child. When

[Lasse Reichstein Nielsen, 2015/01/30 12:11:37]

can communication with the child -> 
can communicate with the child through these.

[Søren Gjesse, 2015/02/02 13:56:44]

Done.

+   * these communication channels are closed the detached process will

[Lasse Reichstein Nielsen, 2015/01/30 12:11:37]

Rewrite as: The detached process will keep running even if these communication
channels are closed.

Is this different from a NORMAL process? If not, no need to write it. If so, say
that a normal process will stop if the input/output is closed.

[Søren Gjesse, 2015/02/02 13:56:44]

Done.

+   * keep running. Its exit code will not become available when it

[Lasse Reichstein Nielsen, 2015/01/30 12:11:37]

Its -> The process'

[Søren Gjesse, 2015/02/02 13:56:44]

Done.

+   * terminated.

[Lasse Reichstein Nielsen, 2015/01/30 12:11:37]

terminated -> terminates.

[Søren Gjesse, 2015/02/02 13:56:44]

Done.

+   *
+   * The default value for `mode` is `ProcessStartMode.NORMAL`.
    */
   external static Future<Process> start(
       String executable,
       List<String> arguments,
       {String workingDirectory,
        Map<String, String> environment,
        bool includeParentEnvironment: true,
        bool runInShell: false,
-       bool detach: false});
+       ProcessStartMode mode: ProcessStartMode.NORMAL});
 
   /**
    * Starts a process and runs it non-interactively to completion. The
    * process run is [executable] with the specified [arguments].
    *
    * Use [workingDirectory] to set the working directory for the process. Note
    * that the change of directory occurs before executing the process on some
    * platforms, which may have impact when using relative paths for the
    * executable and the arguments.
    *
@@ skipping 235 matching lines @@
   final int errorCode;
 
   const ProcessException(this.executable, this.arguments, [this.message = "",
                          this.errorCode = 0]);
   String toString() {
     var msg = (message == null) ? 'OS error code: $errorCode' : message;
     var args = arguments.join(' ');
     return "ProcessException: $msg\n  Command: $executable $args";
   }
 }