Class Grit::Process
In: lib/grit/jruby.rb
lib/grit/process.rb
Parent: Object

Grit::Process includes logic for executing child processes and reading/writing from their standard input, output, and error streams.

Create an run a process to completion:

  >> process = Grit::Process.new(['git', '--help'])

Retrieve stdout or stderr output:

  >> process.out
  => "usage: git [--version] [--exec-path[=GIT_EXEC_PATH]]\n ..."
  >> process.err
  => ""

Check process exit status information:

  >> process.status
  => #<Process::Status: pid=80718,exited(0)>

Grit::Process is designed to take all input in a single string and provides all output as single strings. It is therefore not well suited to streaming large quantities of data in and out of commands.

Q: Why not use popen3 or hand-roll fork/exec code?

  • It‘s more efficient than popen3 and provides meaningful process hierarchies because it performs a single fork/exec. (popen3 double forks to avoid needing to collect the exit status and also calls Process::detach which creates a Ruby Thread!!!!).
  • It‘s more portable than hand rolled pipe, fork, exec code because fork(2) and exec(2) aren‘t available on all platforms. In those cases, Grit::Process falls back to using whatever janky substitutes the platform provides.
  • It handles all max pipe buffer hang cases, which is non trivial to implement correctly and must be accounted for with either popen3 or hand rolled fork/exec code.

Methods

new   popen4   success?   waitpid  

Classes and Modules

Class Grit::Process::MaximumOutputExceeded
Class Grit::Process::TimeoutExceeded

Constants

FakeStatus = Struct.new(:pid, :exitstatus, :success?, :fake?)   JRuby always raises ECHILD on pids returned from its IO.popen4 method for some reason. Return a fake Process::Status object.
BUFSIZE = (32 * 1024)   Maximum buffer size for reading

Attributes

err  [R]  All data written to the child process‘s stderr stream as a String.
out  [R]  All data written to the child process‘s stdout stream as a String.
runtime  [R]  Total command execution time (wall-clock time)
status  [R]  A Process::Status object with information on how the child exited.

Public Class methods

Create and execute a new process.

argv - Array of [command, arg1, …] strings to use as the new

          process's argv. When argv is a String, the shell is used
          to interpret the command.

env - The new process‘s environment variables. This is merged with

          the current environment as if by ENV.merge(env).

options - Additional options:

            :input   => str to write str to the process's stdin.
            :timeout => int number of seconds before we given up.
            :max     => total number of output bytes
          A subset of Process:spawn options are also supported on all
          platforms:
            :chdir => str to start the process in different working dir.

Returns a new Process instance that has already executed to completion. The out, err, and status attributes are immediately available.

Public Instance methods

Use JRuby‘s built in IO.popen4 but emulate the special spawn env and options arguments as best we can.

Determine if the process did exit with a zero exit status.

[Validate]