class BackgroundProcess

Attributes

Public Class Methods

Source

# File lib/background_process/background_process.rb, line 5
def initialize(pid, stdin, stdout, stderr = nil)
  @pid, @stdin, @stdout, @stderr = pid, stdin, stdout, stderr
  ObjectSpace.define_finalizer(self) { kill }
end

Initialize a BackgroundProcess task. Don’t do this. Use BackgroundProcess.run or BackgroundProcess.run_pty instead

run (*command_with_args)

Source

# File lib/background_process/background_process.rb, line 24
def self.run(*command_with_args)
  command = sanitize_command(command_with_args)
  child_stdin, parent_stdin = IO::pipe
  parent_stdout, child_stdout = IO::pipe
  parent_stderr, child_stderr = IO::pipe

  pid = Kernel.fork do
    [parent_stdin, parent_stdout, parent_stderr].each { |io| io.close }

    STDIN.reopen(child_stdin)
    STDOUT.reopen(child_stdout)
    STDERR.reopen(child_stderr)

    [child_stdin, child_stdout, child_stderr].each { |io| io.close }

    exec command
  end

  [child_stdin, child_stdout, child_stderr].each { |io| io.close }
  parent_stdin.sync = true

  new(pid, parent_stdin, parent_stdout, parent_stderr)
end

Run a command, connecting it’s IO streams (stdin, sterr, stdout) via IO pipes, which are not tty IO streams.

Because of this, some programs (like ruby) will buffer their output and only make it available when it’s explicitely flushed (with IO#flush or when the buffer gets full). This behavior can be overridden by setting the streams to sync, like this:

STDOUT.sync, STDERR.sync = true, true

If you can’t control the program and have it explicitly flush its output when it should, or you can’t tell the streams to run in sync mode, see PTYBackgroundProcess.run for a workaround.

sanitize_command (*args)

Source

# File lib/background_process/background_process.rb, line 102
def self.sanitize_command(*args)
  command_and_args = args.flatten
  return command_and_args.first if command_and_args.length == 1
  command_and_args.map { |p| p.gsub(' ', '\ ') }.join(" ")
end

It’s protected. What do you care? :P

Public Instance Methods

detect (which = :both, timeout = nil, &block)

Source

# File lib/background_process/background_process.rb, line 95
def detect(which = :both, timeout = nil, &block)
  streams = select_streams(which)
  BackgroundProcess::IOHelpers.detect(streams, timeout, &block)
end

Calls block each time a line is available in the specified output buffer(s) and returns the first non-false value By default, both stdout and stderr are monitored.

Args:

which: which streams to monitor. valid values are :stdout, :stderr, or :both.
timeout: Total time in seconds to run detect for. If result not found within this time, abort and return nil. Pass nil for no timeout.
&block: the block to call. If block takes two arguments, it will pass both the stream that received the input (an instance of IO, not the symbol), and the line read from the buffer.

exitstatus ()

Source

# File lib/background_process/background_process.rb, line 84
def exitstatus
  wait && wait.exitstatus
end

Waits for the process to terminate, and then returns the exit status

interrupt ()

Source

# File lib/background_process/background_process.rb, line 58
def interrupt
  kill('INT')
end

Sends the interrupt signal to the process. The equivalent of pressing control-C in it.

kill (signal = 'TERM')

Source

# File lib/background_process/background_process.rb, line 50
def kill(signal = 'TERM')
  if running?
    Process.kill(Signal.list[signal], @pid)
    true
  end
end

send a signal to the process. If the processes and running, do nothing. Valid signals are those in Signal.list. Default is “TERM”

running? ()

Source

# File lib/background_process/background_process.rb, line 63
def running?
  return false unless @pid
  Process.getpgid(@pid)
  true
rescue Errno::ESRCH
  false
end

asks the operating system is the process still exists.

wait (timeout = nil)

Source

# File lib/background_process/background_process.rb, line 74
def wait(timeout = nil)
  @exit_status ||= Timeout.timeout(timeout) do
    Process.wait(@pid)
    $?
  end
rescue Timeout::Error
  nil
end

waits for the process to finish. Freeze the process so it can rest in peace. You should call this on every background job you create to avoid a flood of zombie processes. (Processes won’t go away until they are waited on)

Protected Instance Methods

select_streams (which)

Source

# File lib/background_process/background_process.rb, line 108
def select_streams(which)
  case which
  when :stdout then [stdout]
  when :stderr then [stderr]
  when :both   then [stdout, stderr]
  else raise(ArgumentError, "invalid stream specification: #{which}")
  end.compact
end