right_popen 1.0.21 → 1.1.3

data/lib/right_popen/process_status.rb

@@ -0,0 +1,64 @@
+#--
+# Copyright (c) 2013 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+module RightScale
+
+  module RightPopen
+
+    # Quacks like Process::Status, which we cannot instantiate ourselves because
+    # has no public new method for cases where we need to create our own.
+    class ProcessStatus
+
+      attr_reader :pid, :exitstatus, :termsig
+
+      # === Parameters
+      # @param [Integer] pid as process identifier
+      # @param [Integer] exitstatus as process exit code or nil
+      # @param [Integer] termination signal or nil
+      def initialize(pid, exitstatus, termsig=nil)
+        @pid = pid
+        @exitstatus = exitstatus
+        @termsig = termsig
+      end
+
+      # Simulates Process::Status.exited? which seems like a weird method since
+      # this object cannot logically be queried until the process exits.
+      #
+      # === Returns
+      # @return [TrueClass] always true
+      def exited?
+        return true
+      end
+
+      # Simulates Process::Status.success?
+      #
+      # === Returns
+      # true if the process returned zero as its exit code or nil if terminate was signalled
+      def success?
+        # note that Linux ruby returns nil when exitstatus is nil and a termsig
+        # value is set instead.
+        return @exitstatus ? (0 == @exitstatus) : nil
+      end
+    end
+  end
+end

data/lib/right_popen/safe_output_buffer.rb

@@ -0,0 +1,79 @@
+#--
+# Copyright (c) 2013 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+module RightScale
+
+  module RightPopen
+
+    # Provides an output handler implementation that buffers output (from a
+    # child process) while ensuring that the output does not exhaust memory
+    # in the current process. it does this by preserving only the most
+    # interesting bits of data (start of lines, last in output).
+    class SafeOutputBuffer
+
+      # note utf-8 encodings for the Unicode elipsis character are inconsistent
+      # between ruby platforms (Windows vs Linux) and versions (1.8 vs 1.9).
+      ELLIPSIS = '...'
+
+      DEFAULT_MAX_LINE_COUNT = 64
+      DEFAULT_MAX_LINE_LENGTH = 256
+
+      attr_reader :buffer, :max_line_count, :max_line_length
+
+      # === Parameters
+      # @param [Array] buffer for lines
+      # @param [Integer] max_line_count to limit number of lines in buffer
+      # @param [Integer] max_line_length to truncate charcters from start of line
+      def initialize(buffer = [],
+                     max_line_count = DEFAULT_MAX_LINE_COUNT,
+                     max_line_length = DEFAULT_MAX_LINE_LENGTH)
+        raise ArgumentError.new('buffer is required') unless @buffer = buffer
+        raise ArgumentError.new('max_line_count is invalid') unless (@max_line_count = max_line_count) > 1
+        raise ArgumentError.new('max_line_length is invalid') unless (@max_line_length = max_line_length) > ELLIPSIS.length
+      end
+
+      def display_text; @buffer.join("\n"); end
+
+      # Buffers data with specified truncation.
+      #
+      # === Parameters
+      # @param [Object] data of any kind
+      def safe_buffer_data(data)
+        # note that the chomping ensures that the exact output cannot be
+        # preserved but the truncation would tend to eliminate trailing newlines
+        # in any case. if you want exact output then don't use safe buffering.
+        data = data.to_s.chomp
+        if @buffer.size >= @max_line_count
+          @buffer.shift
+          @buffer[0] = ELLIPSIS
+        end
+        if data.length > @max_line_length
+          truncation = [data.length - (@max_line_length - ELLIPSIS.length), 0].max
+          data = "#{data[0..(@max_line_length - ELLIPSIS.length - 1)]}#{ELLIPSIS}"
+        end
+        @buffer << data
+        true
+      end
+    end
+  end
+end

data/lib/right_popen/target_proxy.rb

@@ -0,0 +1,67 @@
+#--
+# Copyright (c) 2013 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+module RightScale
+  module RightPopen
+
+    # proxies calls to target to simplify popen3 implementation code and to make
+    # the proxied callbacks slightly more efficient.
+    class TargetProxy
+
+      HANDLER_NAME_TO_PARAMETER_COUNT = {
+        :exit_handler       => 1,
+        :pid_handler        => 1,
+        :size_limit_handler => 0,
+        :stderr_handler     => 1,
+        :stdout_handler     => 1,
+        :timeout_handler    => 0,
+        :watch_handler      => 1,
+      }
+
+      def initialize(options = {})
+        if options[:target].nil? &&
+           !(options.keys & HANDLER_NAME_TO_PARAMETER_COUNT.keys).empty?
+          raise ArgumentError, "Missing target"
+        end
+        @target = options[:target]  # hold target reference (if any) against GC
+
+        # define an instance method for each handler that either proxies
+        # directly to the target method (with parameters) or else does nothing.
+        HANDLER_NAME_TO_PARAMETER_COUNT.each do |handler_name, parameter_count|
+          parameter_list = (1..parameter_count).map { |i| "p#{i}" }.join(', ')
+          instance_eval <<EOF
+if @target && options[#{handler_name.inspect}]
+  @#{handler_name.to_s}_method = @target.method(options[#{handler_name.inspect}])
+  def #{handler_name.to_s}(#{parameter_list})
+    @#{handler_name.to_s}_method.call(#{parameter_list})
+  end
+else
+  def #{handler_name.to_s}(#{parameter_list}); true; end
+end
+EOF
+          end
+      end
+    end
+
+  end # RightPopen
+end # RightScale

data/lib/right_popen/version.rb

@@ -1,5 +1,5 @@
 #--  -*- mode: ruby; encoding: utf-8 -*-
-# Copyright: Copyright (c) 2011 RightScale, Inc.
+# Copyright: Copyright (c) 2011-2013 RightScale, Inc.
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -23,6 +23,6 @@
 
 module RightScale
   module RightPopen
-    VERSION = "1.0.21"
+    VERSION = "1.1.3"
   end
 end

data/right_popen.gemspec

@@ -47,8 +47,8 @@ EOF
   end
   spec.files = candidates.sort!
 
-  # Current implementation supports >= 0.12.11
-  spec.add_runtime_dependency(%q<eventmachine>, [">= 0.12.11"])
+  # Current implementation supports >= 1.0.0
+  spec.add_development_dependency(%q<eventmachine>, [">= 1.0.0"])
   if is_windows
     spec.add_runtime_dependency(%q<win32-process>, [">= 0.6.1"])
   end

data/spec/produce_mixed_output.rb

@@ -1,6 +1,9 @@
 count = ARGV[0] ? ARGV[0].to_i : 1
 exit_code = ARGV[1] ? ARGV[1].to_i : 0
 
+STDOUT.sync=true
+STDERR.sync=true
+
 count.times do |i|
   $stderr.puts "stderr #{i}" if 0 == i % 10
   $stdout.puts "stdout #{i}"

data/spec/right_popen/linux/accumulator_spec.rb

@@ -33,8 +33,6 @@ module RightScale::RightPopen
     describe "#tick" do
       context 'with a live child' do
         before(:each) do
-          @process.should_receive(:status).and_return(nil)
-          @process.should_receive(:status=)
           @input = flexmock("input")
           @output = flexmock("output")
           @read = flexmock("read")
@@ -155,14 +153,14 @@ module RightScale::RightPopen
         a = Accumulator.new(@process, [], [], [], [])
         status = flexmock("status")
         flexmock(::Process).should_receive(:waitpid2).with(42, ::Process::WNOHANG).once.and_return(status)
-        @process.should_receive(:status).twice.and_return(nil).and_return(status)
-        @process.should_receive(:status=).with(status).once
         a.tick.should be_true
       end
 
       it 'should return true if the process has already been waited on' do
-        @process.should_receive(:status).and_return(true)
         a = Accumulator.new(@process, [], [], [], [])
+        status = flexmock("status")
+        flexmock(::Process).should_receive(:waitpid2).with(42, ::Process::WNOHANG).once.and_return(status)
+        a.tick.should be_true
         a.tick.should be_true
       end
     end
@@ -188,8 +186,6 @@ module RightScale::RightPopen
       it 'should transition from 0 to 1 as pipes are removed' do
         pipe = flexmock("pipe")
         read = flexmock("read")
-        @process.should_receive(:status).and_return(nil)
-        @process.should_receive(:status=)
         a = Accumulator.new(@process, [pipe], [read], [], [])
         flexmock(::IO).should_receive(:select).with([pipe], [], nil, 0.1).once.and_return([[pipe], [], []])
         pipe.should_receive(:eof?).and_return(true)
@@ -203,7 +199,7 @@ module RightScale::RightPopen
 
     describe "#cleanup" do
       it 'should do nothing if no pipes are left open and the process is reaped' do
-        @process.should_receive(:status).and_return(true)
+        pending 'needs refactoring if actually in use'
         a = Accumulator.new(@process, [], [], [], [])
         flexmock(::Process).should_receive(:waitpid2).never
         a.cleanup
@@ -212,16 +208,14 @@ module RightScale::RightPopen
       it 'should just call waitpid if no pipes are left open' do
         value = flexmock("value")
         a = Accumulator.new(@process, [], [], [], [])
-        @process.should_receive(:status).and_return(nil)
         flexmock(::Process).should_receive(:waitpid2).with(42).once.and_return(value)
-        @process.should_receive(:status=).with(value).once
         a.cleanup
       end
 
       it 'should close all open pipes' do
+        pending 'needs refactoring if actually in use'
         a, b, c = flexmock("a"), flexmock("b"), flexmock("c")
         acc = Accumulator.new(@process, [a, b], [], [c], [])
-        @process.should_receive(:status).and_return(true)
         [a, b].each {|fdes| fdes.should_receive(:close).with().once }
         [a, b].each {|fdes| fdes.should_receive(:closed?).and_return(false) }
         [c].each {|fdes| fdes.should_receive(:closed?).and_return(true) }
@@ -233,12 +227,10 @@ module RightScale::RightPopen
         value = flexmock("value")
         a, b, c = flexmock("a"), flexmock("b"), flexmock("c")
         acc = Accumulator.new(@process, [b, c], [], [a], [])
-        @process.should_receive(:status).and_return(nil)
         [a, b].each {|fdes| fdes.should_receive(:close).with().once }
         [a, b].each {|fdes| fdes.should_receive(:closed?).and_return(false) }
         [c].each {|fdes| fdes.should_receive(:closed?).and_return(true) }
         flexmock(::Process).should_receive(:waitpid2).with(42).once.and_return(value)
-        @process.should_receive(:status=).with(value).once
         acc.cleanup
       end
     end

data/spec/right_popen/safe_output_buffer_spec.rb

@@ -0,0 +1,26 @@
+require ::File.expand_path(::File.join(::File.dirname(__FILE__), '..', 'spec_helper'))
+require ::File.expand_path(::File.join(::File.dirname(__FILE__), '..', '..', 'lib', 'right_popen', 'safe_output_buffer'))
+
+describe RightScale::RightPopen::SafeOutputBuffer do
+
+  context 'given a default buffer' do
+    subject { described_class.new }
+
+    it 'should limit line count and length' do
+      (described_class::DEFAULT_MAX_LINE_COUNT * 2).times do |line_index|
+        data = 'x' * rand(described_class::DEFAULT_MAX_LINE_LENGTH * 3)
+        subject.safe_buffer_data(data).should be_true
+      end
+      subject.buffer.size.should == described_class::DEFAULT_MAX_LINE_COUNT
+      subject.buffer.first.should == described_class::ELLIPSIS
+      subject.buffer.last.should_not == described_class::ELLIPSIS
+      subject.buffer.each do |line|
+        (line.length <= described_class::DEFAULT_MAX_LINE_LENGTH).should be_true
+      end
+      text = subject.display_text
+      text.should_not be_empty
+      text.lines.count.should == subject.buffer.size
+    end
+  end
+
+end

data/spec/right_popen_spec.rb

@@ -1,286 +1,331 @@
 require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
 require File.expand_path(File.join(File.dirname(__FILE__), 'runner'))
+
 require 'stringio'
+require 'tmpdir'
 
-module RightScale
-  describe 'popen3' do
-    def is_windows?
-      return !!(RUBY_PLATFORM =~ /mswin/)
-    end
+describe 'RightScale::RightPopen' do
+  def is_windows?
+    return !!(RUBY_PLATFORM =~ /mswin|mingw/)
+  end
 
-    it 'should redirect output' do
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_output.rb'))}\" \"#{STANDARD_MESSAGE}\" \"#{ERROR_MESSAGE}\""
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == 0
-      status.output_text.should == STANDARD_MESSAGE + "\n"
-      status.error_text.should == ERROR_MESSAGE + "\n"
-      status.pid.should > 0
-    end
+  let(:runner) { ::RightScale::RightPopen::Runner.new }
 
-    it 'should return the right status' do
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_status.rb'))}\" #{EXIT_STATUS}"
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == EXIT_STATUS
-      status.output_text.should == ''
-      status.error_text.should == ''
-      status.pid.should > 0
+  it "should correctly handle many small processes [async]" do
+    pending 'Set environment variable TEST_STRESS to enable' unless ENV['TEST_STRESS']
+    run_count = 100
+    command = is_windows? ? ['cmd.exe', '/c', 'exit 0'] : ['sh', '-c', 'exit 0']
+    @completed = 0
+    @started = 0
+    run_cmd = Proc.new do
+      runner.do_right_popen3_async(command, runner_options={}, popen3_options={}) do |runner_status|
+        @completed += 1
+        runner_status.status.exitstatus.should == 0
+        runner_status.output_text.should == ''
+        runner_status.error_text.should == ''
+        runner_status.pid.should > 0
+      end
+      @started += 1
+      if @started < run_count
+        EM.next_tick { run_cmd.call }
+      end
     end
+    EM.run do
+      EM.next_tick { run_cmd.call }
 
-    it 'should correctly handle many small processes' do
-      pending 'Set environment variable TEST_STRESS to enable' unless ENV['TEST_STRESS']
-      TO_RUN = 100
-      command = is_windows? ? "cmd.exe /c exit 0" : "exit 0"
-      runner = Runner.new
-      @completed = 0
-      @started = 0
-      run_cmd = Proc.new do
-        runner.do_right_popen(command) do |status|
-          @completed += 1
-          status.status.exitstatus.should == 0
-          status.output_text.should == ''
-          status.error_text.should == ''
-          status.pid.should > 0
-        end
-        @started += 1
-        if @started < TO_RUN
-          EM.next_tick { run_cmd.call }
+      EM::PeriodicTimer.new(1) do
+        if @completed >= run_count
+          EM.stop
         end
       end
-      EM.run do
-        EM.next_tick { run_cmd.call }
+    end
+  end
+
+  [:sync, :async].each do |synchronicity|
+
+    context synchronicity do
+
+      it "should redirect output" do
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_output.rb'))}\" \"#{STANDARD_MESSAGE}\" \"#{ERROR_MESSAGE}\""
+        runner_status = runner.run_right_popen3(synchronicity, command)
+        runner_status.should_not be_nil
+        runner_status.status.should_not be_nil
+        runner_status.status.exitstatus.should == 0
+        runner_status.output_text.should == STANDARD_MESSAGE + "\n"
+        runner_status.error_text.should == ERROR_MESSAGE + "\n"
+        runner_status.pid.should > 0
+      end
+
+      it "should return the right status" do
+        ruby = `which ruby`.chomp  # which is assumed to be on the PATH for the Windows case
+        command = [
+          ruby,
+          File.expand_path(File.join(File.dirname(__FILE__), 'produce_status.rb')),
+          EXIT_STATUS
+        ]
+        status = runner.run_right_popen3(synchronicity, command)
+        status.status.exitstatus.should == EXIT_STATUS
+        status.output_text.should == ''
+        status.error_text.should == ''
+        status.pid.should > 0
+      end
 
-        EM::PeriodicTimer.new(1) do
-          if @completed >= TO_RUN
-            EM.stop
+      it "should close all IO handlers, except STDIN, STDOUT and STDERR" do
+        GC.start
+        command = [
+          RUBY_CMD,
+          File.expand_path(File.join(File.dirname(__FILE__), 'produce_status.rb')),
+          EXIT_STATUS
+        ]
+        status = runner.run_right_popen3(synchronicity, command)
+        status.status.exitstatus.should == EXIT_STATUS
+        useless_handlers = 0
+        ObjectSpace.each_object(IO) do |io|
+          if ![STDIN, STDOUT, STDERR].include?(io)
+            useless_handlers += 1 unless io.closed?
           end
         end
+        useless_handlers.should == 0
       end
-    end
 
-    it 'should close all IO handlers, except STDIN, STDOUT and STDERR' do
-      GC.start
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_status.rb'))}\" #{EXIT_STATUS}"
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == EXIT_STATUS
-      useless_handlers = 0
-      ObjectSpace.each_object(IO) do |io|
-        if ![STDIN, STDOUT, STDERR].include?(io)
-          useless_handlers += 1 unless io.closed?
+      it "should preserve the integrity of stdout when stderr is unavailable" do
+        count = LARGE_OUTPUT_COUNTER
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_stdout_only.rb'))}\" #{count}"
+        status = runner.run_right_popen3(synchronicity, command)
+        status.status.exitstatus.should == 0
+
+        results = ''
+        count.times do |i|
+          results << "stdout #{i}\n"
         end
+        status.output_text.should == results
+        status.error_text.should == ''
+        status.pid.should > 0
       end
-      useless_handlers.should == 0
-    end
 
-    it 'should preserve the integrity of stdout when stderr is unavailable' do
-      count = LARGE_OUTPUT_COUNTER
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_stdout_only.rb'))}\" #{count}"
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == 0
+      it "should preserve the integrity of stderr when stdout is unavailable" do
+        count = LARGE_OUTPUT_COUNTER
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_stderr_only.rb'))}\" #{count}"
+        status = runner.run_right_popen3(synchronicity, command)
+        status.status.exitstatus.should == 0
 
-      results = ''
-      count.times do |i|
-        results << "stdout #{i}\n"
+        results = ''
+        count.times do |i|
+          results << "stderr #{i}\n"
+        end
+        status.error_text.should == results
+        status.output_text.should == ''
+        status.pid.should > 0
       end
-      status.output_text.should == results
-      status.error_text.should == ''
-      status.pid.should > 0
-    end
 
-    it 'should preserve the integrity of stderr when stdout is unavailable' do
-      count = LARGE_OUTPUT_COUNTER
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_stderr_only.rb'))}\" #{count}"
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == 0
+      it "should preserve interleaved output when yielding CPU on consumer thread" do
+        lines = 11
+        exit_code = 42
+        repeats = 5
+        force_yield = 0.1
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_mixed_output.rb'))}\" #{lines} #{exit_code}"
+        actual_output = StringIO.new
+        actual_error = StringIO.new
+        puts
+        stats = runner.run_right_popen3(synchronicity, command, :repeats=>repeats, :force_yield=>force_yield) do |status|
+          status.status.exitstatus.should == exit_code
+          status.pid.should > 0
+          actual_output << status.output_text
+          actual_error << status.error_text
+        end
+        puts
+        stats.size.should == repeats
+
+        expected_output = StringIO.new
+        repeats.times do
+          lines.times do |i|
+            expected_output << "stdout #{i}\n"
+          end
+        end
+        actual_output.string.should == expected_output.string
 
-      results = ''
-      count.times do |i|
-        results << "stderr #{i}\n"
+        expected_error = StringIO.new
+        repeats.times do
+          lines.times do |i|
+            (expected_error << "stderr #{i}\n") if 0 == i % 10
+          end
+        end
+        actual_error.string.should == expected_error.string
       end
-      status.error_text.should == results
-      status.output_text.should == ''
-      status.pid.should > 0
-    end
 
-    it 'should preserve interleaved output when yielding CPU on consumer thread' do
-      lines = 11
-      exit_code = 42
-      repeats = 5
-      force_yield = 0.1
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_mixed_output.rb'))}\" #{lines} #{exit_code}"
-      runner = Runner.new
-      actual_output = StringIO.new
-      actual_error = StringIO.new
-      puts
-      stats = runner.run_right_popen(command, :repeats=>repeats, :force_yield=>force_yield) do |status|
+      it "should preserve interleaved output when process is spewing rapidly" do
+        lines = LARGE_OUTPUT_COUNTER
+        exit_code = 99
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_mixed_output.rb'))}\" #{lines} #{exit_code}"
+        status = runner.run_right_popen3(synchronicity, command, :timeout=>10)
         status.status.exitstatus.should == exit_code
-        status.pid.should > 0
-        actual_output << status.output_text
-        actual_error << status.error_text
-        print '+'
-      end
-      puts
-      stats.size.should == repeats
 
-      expected_output = StringIO.new
-      repeats.times do
+        expected_output = StringIO.new
         lines.times do |i|
           expected_output << "stdout #{i}\n"
         end
-      end
-      actual_output.string.should == expected_output.string
+        status.output_text.should == expected_output.string
 
-      expected_error = StringIO.new
-      repeats.times do
+        expected_error = StringIO.new
         lines.times do |i|
           (expected_error << "stderr #{i}\n") if 0 == i % 10
         end
+        status.error_text.should == expected_error.string
+        status.pid.should > 0
       end
-      actual_error.string.should == expected_error.string
-    end
 
-    it 'should preserve interleaved output when process is spewing rapidly' do
-      lines = LARGE_OUTPUT_COUNTER
-      exit_code = 99
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_mixed_output.rb'))}\" #{lines} #{exit_code}"
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == exit_code
-
-      expected_output = StringIO.new
-      lines.times do |i|
-        expected_output << "stdout #{i}\n"
+      it "should setup environment variables" do
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
+        status = runner.run_right_popen3(synchronicity, command)
+        status.status.exitstatus.should == 0
+        status.output_text.should_not include('_test_')
+        status = runner.run_right_popen3(synchronicity, command, :env=>{ :__test__ => '42' })
+        status.status.exitstatus.should == 0
+        status.output_text.should match(/^__test__=42$/)
+        status.pid.should > 0
       end
-      status.output_text.should == expected_output.string
 
-      expected_error = StringIO.new
-      lines.times do |i|
-        (expected_error << "stderr #{i}\n") if 0 == i % 10
+      it "should restore environment variables" do
+        begin
+          ENV['__test__'] = '41'
+          old_envs = {}
+          ENV.each { |k, v| old_envs[k] = v }
+          command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
+          status = runner.run_right_popen3(synchronicity, command, :env=>{ :__test__ => '42' })
+          status.status.exitstatus.should == 0
+          status.output_text.should match(/^__test__=42$/)
+          ENV.each { |k, v| old_envs[k].should == v }
+          old_envs.each { |k, v| ENV[k].should == v }
+          status.pid.should > 0
+        ensure
+          ENV.delete('__test__')
+        end
       end
-      status.error_text.should == expected_error.string
-      status.pid.should > 0
-    end
 
-    it 'should setup environment variables' do
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == 0
-      status.output_text.should_not include('_test_')
-      status = runner.run_right_popen(command, :env=>{ :__test__ => '42' })
-      status.status.exitstatus.should == 0
-      status.output_text.should match(/^__test__=42$/)
-      status.pid.should > 0
-    end
+      if is_windows?
+        # FIX: this behavior is currently specific to Windows but should probably be
+        # implemented for Linux.
+        it "should merge the PATH variable instead of overriding it" do
+          command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
+          status = runner.run_right_popen3(synchronicity, command, :env=>{ 'PATH' => "c:/bogus\\bin" })
+          status.status.exitstatus.should == 0
+          status.output_text.should include('c:\\bogus\\bin;')
+          status.pid.should > 0
+        end
+      else
+        it "should allow running bash command lines starting with a built-in command" do
+          command = "for i in 1 2 3 4 5; do echo $i;done"
+          status = runner.run_right_popen3(synchronicity, command)
+          status.status.exitstatus.should == 0
+          status.output_text.should == "1\n2\n3\n4\n5\n"
+          status.pid.should > 0
+        end
 
-    it 'should restore environment variables' do
-      begin
-        ENV['__test__'] = '41'
-        old_envs = {}
-        ENV.each { |k, v| old_envs[k] = v }
-        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
-        runner = Runner.new
-        status = runner.run_right_popen(command, :env=>{ :__test__ => '42' })
-        status.status.exitstatus.should == 0
-        status.output_text.should match(/^__test__=42$/)
-        ENV.each { |k, v| old_envs[k].should == v }
-        old_envs.each { |k, v| ENV[k].should == v }
-        status.pid.should > 0
-      ensure
-        ENV.delete('__test__')
+        it "should support running background processes" do
+          command = "(sleep 20)&"
+          now = Time.now
+          status = runner.run_right_popen3(synchronicity, command)
+          finished = Time.now
+          (finished - now).should < 20
+          status.did_timeout.should be_false
+          status.status.exitstatus.should == 0
+          status.output_text.should == ""
+          status.pid.should > 0
+        end
       end
-    end
 
-    if is_windows?
-      # FIX: this behavior is currently specific to Windows but should probably be
-      # implemented for Linux.
-      it 'should merge the PATH variable instead of overriding it' do
-        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'print_env.rb'))}\""
-        runner = Runner.new
-        status = runner.run_right_popen(command, :env=>{ 'PATH' => "c:/bogus\\bin" })
+      it "should support raw command arguments" do
+        command = is_windows? ? ["cmd.exe", "/c", "echo", "*"] : ["echo", "*"]
+        status = runner.run_right_popen3(synchronicity, command)
         status.status.exitstatus.should == 0
-        status.output_text.should include('c:\\bogus\\bin;')
+        status.output_text.should == "*\n"
         status.pid.should > 0
       end
-    else
-      it 'should allow running bash command lines starting with a built-in command' do
-        command = "for i in 1 2 3 4 5; do echo $i;done"
-        runner = Runner.new
-        status = runner.run_right_popen(command)
-        status.status.exitstatus.should == 0
-        status.output_text.should == "1\n2\n3\n4\n5\n"
-        status.pid.should > 0
+
+      it "should run repeatedly without leaking resources" do
+        pending 'Set environment variable TEST_LEAK to enable' unless ENV['TEST_LEAK']
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_output.rb'))}\" \"#{STANDARD_MESSAGE}\" \"#{ERROR_MESSAGE}\""
+        stats = runner.run_right_popen3(synchronicity, command, :repeats=>REPEAT_TEST_COUNTER)
+        stats.each do |status|
+          status.status.exitstatus.should == 0
+          status.output_text.should == STANDARD_MESSAGE + "\n"
+          status.error_text.should == ERROR_MESSAGE + "\n"
+          status.pid.should > 0
+        end
       end
 
-      it 'should support running background processes' do
-        command = "(sleep 20)&"
-        now = Time.now
-        runner = Runner.new
-        status = runner.run_right_popen(command)
-        finished = Time.now
-        (finished - now).should < 20
-        status.did_timeout.should be_false
+      it "should pass input to child process" do
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'increment.rb'))}\""
+        status = runner.run_right_popen3(synchronicity, command, :input=>"42\n")
         status.status.exitstatus.should == 0
-        status.output_text.should == ""
+        status.output_text.should == "43\n"
+        status.error_text.should be_empty
         status.pid.should > 0
       end
-    end
 
-    it 'should support raw command arguments' do
-      command = is_windows? ? ["cmd.exe", "/c", "echo", "*"] : ["echo", "*"]
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == 0
-      status.output_text.should == "*\n"
-      status.pid.should > 0
-    end
+      it "should run long child process without any watches by default" do
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'sleeper.rb'))}\""
+        runner_status = runner.run_right_popen3(synchronicity, command, :timeout=>nil)
+        runner_status.status.exitstatus.should == 0
+        runner_status.did_timeout.should be_false
+        runner_status.output_text.should == "To sleep... 0\nTo sleep... 1\nTo sleep... 2\nTo sleep... 3\nThe sleeper must awaken.\n"
+        runner_status.error_text.should == "Perchance to dream... 0\nPerchance to dream... 1\nPerchance to dream... 2\nPerchance to dream... 3\n"
+      end
 
-    it 'should run repeatedly without leaking resources' do
-      pending 'Set environment variable TEST_LEAK to enable' unless ENV['TEST_LEAK']
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_output.rb'))}\" \"#{STANDARD_MESSAGE}\" \"#{ERROR_MESSAGE}\""
-      runner = Runner.new
-      stats = runner.run_right_popen(command, :repeats=>REPEAT_TEST_COUNTER)
-      stats.each do |status|
-        status.status.exitstatus.should == 0
-        status.output_text.should == STANDARD_MESSAGE + "\n"
-        status.error_text.should == ERROR_MESSAGE + "\n"
-        status.pid.should > 0
+      it "should interrupt watched child process when timeout expires" do
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'sleeper.rb'))}\" 10"
+        runner_status = runner.run_right_popen3(synchronicity, command, :expect_timeout=>true, :timeout=>0.1)
+        runner_status.status.success?.should be_false
+        runner_status.did_timeout.should be_true
+        runner_status.output_text.should_not be_empty
+        runner_status.error_text.should_not be_empty
       end
-    end
 
-    it 'should pass input to child process' do
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'increment.rb'))}\""
-      runner = Runner.new
-      status = runner.run_right_popen(command, :input=>"42\n")
-      status.status.exitstatus.should == 0
-      status.output_text.should == "43\n"
-      status.error_text.should be_empty
-      status.pid.should > 0
-    end
+      it "should allow watched child to write files up to size limit" do
+        ::Dir.mktmpdir do |watched_dir|
+          command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'writer.rb'))}\" \"#{watched_dir}\""
+          runner_status = runner.run_right_popen3(synchronicity, command, :size_limit_bytes=>1000, :watch_directory=>watched_dir, :timeout=>10)
+          runner_status.status.success?.should be_true
+          runner_status.did_size_limit.should be_false
+        end
+      end
 
-    it 'should handle child processes that close stdout but keep running' do
-	  pending 'not implemented for windows' if is_windows?
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'stdout.rb'))}\""
-      runner = Runner.new
-      status = runner.run_right_popen(command, :expect_timeout=>true, :timeout=>2)
-      status.did_timeout.should be_true
-      status.output_text.should be_empty
-      status.error_text.should == "Closing stdout\n"
-    end
+      it "should interrupt watched child at size limit" do
+        ::Dir.mktmpdir do |watched_dir|
+          command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'writer.rb'))}\" \"#{watched_dir}\""
+          runner_status = runner.run_right_popen3(synchronicity, command, :expect_size_limit=>true, :size_limit_bytes=>100, :watch_directory=>watched_dir, :timeout=>10)
+          runner_status.status.success?.should be_false
+          runner_status.did_size_limit.should be_true
+        end
+      end
+
+      it "should handle child processes that close stdout but keep running" do
+        pending 'not implemented for windows' if is_windows? && :sync != synchronicity
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'stdout.rb'))}\""
+        runner_status = runner.run_right_popen3(synchronicity, command, :expect_timeout=>true, :timeout=>2)
+        runner_status.output_text.should be_empty
+        runner_status.error_text.should == "Closing stdout\n"
+        runner_status.did_timeout.should be_true
+      end
 
-    it 'should handle child processes that spawn long running background processes' do
-	  pending 'not implemented for windows' if is_windows?
-      command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'background.rb'))}\""
-      runner = Runner.new
-      status = runner.run_right_popen(command)
-      status.status.exitstatus.should == 0
-      status.did_timeout.should be_false
-      status.output_text.should be_empty
-      status.error_text.should be_empty
+      it "should handle child processes that spawn long running background processes" do
+        pending 'not implemented for windows' if is_windows?
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'background.rb'))}\""
+        status = runner.run_right_popen3(synchronicity, command)
+        status.status.exitstatus.should == 0
+        status.did_timeout.should be_false
+        status.output_text.should be_empty
+        status.error_text.should be_empty
+      end
+
+      it "should run long child process without any watches by default" do
+        command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'sleeper.rb'))}\""
+        runner_status = runner.run_right_popen3(synchronicity, command, :timeout=>nil)
+        runner_status.status.exitstatus.should == 0
+        runner_status.did_timeout.should be_false
+        runner_status.output_text.should == "To sleep... 0\nTo sleep... 1\nTo sleep... 2\nTo sleep... 3\nThe sleeper must awaken.\n"
+        runner_status.error_text.should == "Perchance to dream... 0\nPerchance to dream... 1\nPerchance to dream... 2\nPerchance to dream... 3\n"
+      end
     end
   end
 end