background_process 1.1 → 1.2

data/README.textile

@@ -1,7 +1,7 @@
 h1. Background Process
 
-This is like popen4, but provides several convenience methods for interacting 
-with the process. It only works on UNIX and Ruby implementations that support 
+This is like popen4, but provides several convenience methods for interacting
+with the process. It only works on UNIX and Ruby implementations that support
 fork and native UNIX I/O streams.
 
 "Click here for Complete Documentation":http://rdoc.info/projects/timcharper/background_process
@@ -50,6 +50,33 @@ h2. Common signal names
 | USR1   | 30 |
 | USR2   | 31 |
 
+h2. A word about buffered output
+
+Some processes (like Ruby) buffer their output if they detect that they aren't
+attached to a tty. This means that unless the program explicitly calls
+STDOUT.flush, much of the output won't be available for reading until the
+buffer is full, forcing it to be flushed.
+
+You can force the output of a ruby script to be unbuffered by using a wrapper
+like the following:
+
+<pre>
+  BackgroundProcess.run %(ruby -e 'STDERR.sync, STDOUT.sync = true, true; $0="./server.rb"; load "server.rb"')
+</pre>
+
+If no such workaround is available, this gem provides PTYBackgroundProcess
+which will wrap the command any pseudo-terminal interface. This has the
+advantage of forcing many programs to not buffer their output, but at a
+disadvantage too (you can't get the exit status of the process, you lose any
+output that hasn't been read yet when the process exits, and stderr gets
+merged into stdout). It seems there should be ways to work around these
+limitations, but I wasn't able to figure out an way to do it (without
+resorting to C code at least). Given your circumstances, this may fit your
+needs and be a viable solution to you.
+
+Please see the documentation for BackgroundProcess.run and
+PTYBackgroundProcess.run for further information.
+
 h2. Author
 
 Tim Harper, on behalf of Lead Media Partners

data/lib/background_process.rb

@@ -1,2 +1,3 @@
 require File.dirname(__FILE__) + "/background_process/background_process"
+require File.dirname(__FILE__) + "/background_process/pty_background_process"
 require File.dirname(__FILE__) + "/background_process/io_helpers"

data/lib/background_process/background_process.rb

@@ -1,14 +1,27 @@
 class BackgroundProcess
   attr_reader :stdin, :stdout, :stderr, :pid
 
-  # Initialize a BackgroundProcess task. Don't do this.  Use BackgroundProcess.run instead
-  def initialize(pid, stdin, stdout, stderr)
+  # Initialize a BackgroundProcess task. Don't do this.  Use BackgroundProcess.run or BackgroundProcess.run_pty instead
+  def initialize(pid, stdin, stdout, stderr = nil)
     @pid, @stdin, @stdout, @stderr = pid, stdin, stdout, stderr
     ObjectSpace.define_finalizer(self) { kill }
   end
 
-	# Run a BackgroundProcess
-  def self.run(command, &block)
+
+  # 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.
+  def self.run(command)
     command = sanitize_params(command) if command.is_a?(Array)
     child_stdin, parent_stdin = IO::pipe
     parent_stdout, child_stdout = IO::pipe
@@ -80,12 +93,7 @@ class BackgroundProcess
   # * 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.
   def detect(which = :both, timeout = nil, &block)
-    streams = case which
-              when :stdout then [stdout]
-              when :stderr then [stderr]
-              when :both   then [stdout, stderr]
-              else raise(ArgumentError, "invalid stream specification: #{which}")
-              end
+    streams = select_streams(which)
     BackgroundProcess::IOHelpers.detect(streams, timeout, &block)
   end
 
@@ -94,4 +102,13 @@ class BackgroundProcess
   def self.sanitize_params(params)
     params.map { |p| p.gsub(' ', '\ ') }.join(" ")
   end
+
+  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
 end

data/lib/background_process/pty_background_process.rb

@@ -0,0 +1,64 @@
+require 'pty'
+
+class PTYBackgroundProcess < BackgroundProcess
+  # Runs a subprocess in a pseudo terminal, tricking a program into not
+  # buffering its output.
+  #
+  # A great write up on pseudo-terminals here:
+  # http://stackoverflow.com/questions/1154846/continuously-read-from-stdout-of-external-process-in-ruby
+  #
+  # It has the following disadvantages:
+  # * You can't get the exit status
+  # * When the process dies, whatever output you haven't read yet is lost.
+  # * stderr is merged into stdout
+  def self.run(command)
+    thread = Thread.new do # why run PTY separate thread? When a PTY instance
+                           # dies, it raises PTY::ChildExited on the thread that
+                           # spawned it, interrupting whatever happens to be
+                           # running at the time
+      PTY.spawn(command) do |output, input, pid|
+        begin
+          bp = new(pid, input, output)
+          Thread.current[:background_process] = bp
+          bp.wait
+        rescue Exception => e
+          puts e
+          puts e.backtrace
+        end
+      end
+    end
+    sleep 0.01 until thread[:background_process]
+    thread[:background_process]
+  end
+
+  def stderr
+    raise ArgumentError, "stderr is merged into stdout with PTY subprocesses"
+  end
+
+  def wait(timeout = nil)
+    begin
+      Timeout.timeout(timeout) do
+        Process.wait(@pid)
+      end
+    rescue Timeout::Error
+      nil
+    rescue PTY::ChildExited
+      true
+    rescue Errno::ECHILD
+      true
+    end
+  end
+
+  def exitstatus
+    raise ArgumentError, "exitstatus is not available for PTY subprocesses"
+  end
+
+protected
+  def select_streams(which)
+    case which
+    when :stderr        then stderr # let stderr throw the exception
+    when :stdout, :both then [stdout]
+    else raise(ArgumentError, "invalid stream specification: #{which}")
+    end.compact
+  end
+end

data/spec/background_process/pty_background_process_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+describe PTYBackgroundProcess do
+  describe ".run" do
+    it "runs a subprocess with streams that are identified as tty's" do
+      process = PTYBackgroundProcess.run("env PS1='$' sh")
+      process.stdin.should be_tty
+      process.stdout.should be_tty
+      process.kill
+    end
+
+    it "allows bidirectional communication with the process" do
+      process = PTYBackgroundProcess.run("env PS1='$' sh")
+      process.stdout.getc # wait for the prompt
+      process.stdin.puts "echo Hello World"
+      process.stdout.gets.chomp.should == "echo Hello World"
+      process.stdout.gets.chomp.should == "Hello World"
+      process.stdin.puts "exit"
+      process.wait
+    end
+  end
+
+  describe "#exitstatus" do
+    it "raises an error if you query it" do
+      process = PTYBackgroundProcess.run("exit 1")
+      lambda {process.exitstatus}.should raise_error(ArgumentError, /not available/)
+    end
+  end
+
+  describe "#stderr" do
+    it "raises if you try to access it" do
+      process = PTYBackgroundProcess.run("exit 1")
+      lambda {process.stderr}.should raise_error(ArgumentError, /merged.+stdout/)
+    end
+  end
+
+  describe "#detect" do
+    it "you would expect" do
+      process = PTYBackgroundProcess.run("bash -c 'echo output; echo error 1>&2'")
+      process.detect { |line| true if line =~ /output/ }.should be_true
+      process.detect { |line| true if line =~ /error/ }.should be_true
+    end
+
+    it "raises if you try to select :stderr only" do
+      process = PTYBackgroundProcess.run("bash -c 'echo output; echo error 1>&2'")
+      lambda { process.detect(:stderr) { |line| true } }.should raise_error(ArgumentError, /merged.+stdout/)
+    end
+  end
+end

metadata

@@ -4,8 +4,8 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
-  - 1
-  version: "1.1"
+  - 2
+  version: "1.2"
 platform: ruby
 authors: 
 - Tim Harper
@@ -13,7 +13,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-22 00:00:00 -06:00
+date: 2010-04-28 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
@@ -32,9 +32,11 @@ files:
 - MIT-LICENSE
 - lib/background_process/background_process.rb
 - lib/background_process/io_helpers.rb
+- lib/background_process/pty_background_process.rb
 - lib/background_process.rb
 - spec/background_process/background_process_spec.rb
 - spec/background_process/io_helpers_spec.rb
+- spec/background_process/pty_background_process_spec.rb
 - spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/timcharper/background_process
@@ -70,4 +72,5 @@ summary: background_process
 test_files: 
 - spec/background_process/background_process_spec.rb
 - spec/background_process/io_helpers_spec.rb
+- spec/background_process/pty_background_process_spec.rb
 - spec/spec_helper.rb