right_popen 1.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 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.

data/README.rdoc

@@ -0,0 +1,119 @@
+= RightPopen
+
+== DESCRIPTION
+
+=== Synopsis
+
+RightPopen allows running external processes aynchronously while still
+capturing their standard and error outputs. It relies on EventMachine for most
+of its internal mechanisms. The Linux implementation is valid for any Linux
+platform but there is also a native implementation for Windows platforms.
+
+Refer to the wiki (https://github.com/rightscale/right_popen/wikis) for up-to-date
+documentation.
+
+Also use the built-in issues tracker (https://github.com/rightscale/right_popen/issues)
+to report issues.
+
+
+== USAGE
+
+=== Simple Example
+
+  require 'rubygems'
+  require 'right_popen'
+
+  @stdout_text = ""
+  @stderr_text = ""
+  @exit_status = nil
+
+  def on_read_stdout(data)
+    @stdout_text << data
+  end
+
+  def on_read_stderr(data)
+    @stderr_text << data
+  end
+
+  def on_exit(status)
+    @exit_status = status
+  end
+
+  EM.run do
+    EM.next_tick do
+      cmd = "ruby -e \"puts 'some stdout text'; $stderr.puts 'some stderr text'\; exit 99\""
+      RightScale.popen3(cmd, self, :on_read_stdout, :on_read_stderr, :on_exit)
+    end
+    timer = EM::PeriodicTimer.new(0.1) do
+      if @exit_status
+        timer.cancel
+        EM.stop
+      end
+    end
+  end
+
+  puts "@stdout_text = #{@stdout_text}"
+  puts "@stderr_text = #{@stderr_text}"
+  puts "@exit_status.exitstatus = #{@exit_status.exitstatus}"
+
+
+== INSTALLATION
+
+RightPopen can be installed by entering the following at the command prompt:
+
+  gem install right_popen
+
+
+== BUILDING
+
+Install the following RubyGems required for building:
+* rake
+
+The Windows implementation relies on a native C module which must currently be
+built using the MSVC 6.0 compiler due to a dependency on the standard libraries
+FILE struct provided by the "msvcrt.dll".
+
+The gem can be built on Linux or Windows platforms and will produce separate gem
+files depending on current platform. Run the following command from the
+directory containing the "Rakefile":
+
+  rake build_binary_gem
+
+
+== TESTING
+
+Install the following RubyGems required for testing:
+* rspec
+
+The build can be tested using the RSpec gem. Create a link to the installed
+"spec" in your Ruby/bin directory (or ensure the bin directory is on the PATH
+under Windows) and run the following command from the gem directory to execute
+the RightPopen tests:
+
+  spec spec/right_popen_spec.rb
+
+
+== LICENSE
+
+<b>RightPopen</b>
+
+Copyright:: Copyright (c) 2010 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.

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'fileutils'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rbconfig'
+
+include Config
+
+desc "Clean any build files for right_popen"
+task :clean do
+  if File.exists?('ext/Makefile')
+    Dir.chdir('ext') do
+      sh 'nmake distclean'
+    end
+  end
+  rm 'lib/win32/right_popen.so' if File.file?('lib/win32/right_popen.so')
+end
+
+desc "Build right_popen (but don't install it)"
+task :build => [:clean] do
+  if RUBY_PLATFORM =~ /mswin/
+    Dir.chdir('ext') do
+      ruby 'extconf.rb'
+      sh 'nmake'
+    end
+    FileUtils::mkdir_p 'lib/win32'
+    mv 'ext/right_popen.so', 'lib/win32'
+  end
+end
+
+desc "Build a binary gem"
+task :build_binary_gem => [:build] do
+   Dir["*.gem"].each { |gem| rm gem }
+   ruby 'right_popen.gemspec'
+end
+
+desc 'Install the right_popen library as a gem'
+task :install_gem => [:build_binary_gem] do
+   file = Dir["*.gem"].first
+   sh "gem install #{file}"
+end
+
+desc 'Uninstalls and reinstalls the right_popen library as a gem'
+task :reinstall_gem do
+   sh "gem uninstall right_popen"
+   sh "rake install_gem"
+end

data/lib/linux/right_popen.rb

@@ -0,0 +1,139 @@
+#
+# Copyright (c) 2009 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.
+#
+
+# RightScale.popen3 allows running external processes aynchronously
+# while still capturing their standard and error outputs.
+# It relies on EventMachine for most of its internal mechanisms.
+
+require 'rubygems'
+gem 'eventmachine', '=0.12.8'  # has only been tested with 0.12.8
+require 'eventmachine'
+
+module RightScale
+
+  # Provides an eventmachine callback handler for the stdout stream.
+  module StdOutHandler
+
+    # === Parameters
+    # target(Object):: Object defining handler methods to be called.
+    #
+    # stdout_handler(String):: Token for stdout handler method name.
+    #
+    # exit_handler(String):: Token for exit handler method name.
+    #
+    # stderr_eventable(Connector):: EM object representing stderr handler.
+    #
+    # read_fd(IO):: Standard output read file descriptor.
+    #
+    # write_fd(IO):: Standard output write file descriptor.
+    def initialize(target, stdout_handler, exit_handler, stderr_eventable, read_fd, write_fd)
+      @target = target
+      @stdout_handler = stdout_handler
+      @exit_handler = exit_handler
+      @stderr_eventable = stderr_eventable
+      # Just so they don't get GCed before the process goes away
+      @read_fd = read_fd
+      @write_fd = write_fd
+    end
+
+    # Callback from EM to receive data.
+    def receive_data(data)
+      @target.method(@stdout_handler).call(data) if @stdout_handler
+    end
+
+    # Callback from EM to unbind.
+    def unbind
+      # We force the attached stderr handler to go away so that
+      # we don't end up with a broken pipe
+      @stderr_eventable.force_detach if @stderr_eventable
+      @target.method(@exit_handler).call(get_status) if @exit_handler
+    end
+  end
+
+  module StdErrHandler
+
+    # === Parameters
+    # target(Object):: Object defining handler methods to be called.
+    #
+    # stderr_handler(String):: Token for stderr handler method name.
+    def initialize(target, stderr_handler)
+      @target = target
+      @stderr_handler = stderr_handler
+      @unbound = false
+    end
+
+    # Callback from EM to receive data.
+    def receive_data(data)
+      @target.method(@stderr_handler).call(data)
+    end
+
+    # Callback from EM to unbind.
+    def unbind
+      @unbound = true
+    end
+
+    # Forces detachment of the stderr handler on EM's next tick.
+    def force_detach
+      # Use next tick to prevent issue in EM where descriptors list
+      # gets out-of-sync when calling detach in an unbind callback
+      EM.next_tick { detach unless @unbound }
+    end
+  end
+
+  # Forks process to run given command asynchronously, hooking all three
+  # standard streams of the child process.
+  #
+  # Streams the command's stdout and stderr to the given handlers. Time-
+  # ordering of bytes sent to stdout and stderr is not preserved.
+  #
+  # Calls given exit handler upon command process termination, passing in the
+  # resulting Process::Status.
+  #
+  # All handlers must be methods exposed by the given target.
+  #
+  # === Parameters
+  # cmd(String):: command to execute, including any arguments.
+  #
+  # target(Object):: object defining handler methods to be called.
+  #
+  # stdout_handler(String):: token for stdout handler method name.
+  #
+  # stderr_handler(String):: token for stderr handler method name.
+  #
+  # exit_handler(String):: token for exit handler method name.
+  def self.popen3(cmd, target, stdout_handler = nil, stderr_handler = nil, exit_handler = nil)
+    raise "EventMachine reactor must be started" unless EM.reactor_running?
+    EM.next_tick do
+      saved_stderr = $stderr.dup
+      r, w = Socket::pair(Socket::AF_LOCAL, Socket::SOCK_STREAM, 0)#IO::pipe
+
+      $stderr.reopen w
+      c = EM.attach(r, StdErrHandler, target, stderr_handler) if stderr_handler
+      EM.popen(cmd, StdOutHandler, target, stdout_handler, exit_handler, c, r, w)
+      # Do not close 'w', strange things happen otherwise
+      # (command protocol socket gets closed during decommission) 
+      $stderr.reopen saved_stderr
+    end
+  end
+
+end

data/lib/right_popen.rb

@@ -0,0 +1,32 @@
+#
+# Copyright (c) 2009 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.
+#
+
+# RightScale.popen3 allows running external processes aynchronously
+# while still capturing their standard and error outputs.
+# It relies on EventMachine for most of its internal mechanisms.
+
+if RUBY_PLATFORM =~ /mswin/
+  require File.expand_path(File.join(File.dirname(__FILE__), 'win32', 'right_popen'))
+else
+  require File.expand_path(File.join(File.dirname(__FILE__), 'linux', 'right_popen'))
+end

data/right_popen.gemspec

@@ -0,0 +1,59 @@
+require 'rubygems'
+
+spec = Gem::Specification.new do |spec|
+  is_windows = RUBY_PLATFORM =~ /mswin/
+
+  spec.name      = 'right_popen'
+  spec.version   = '1.0.1'
+  spec.authors   = ['Scott Messier', 'Raphael Simon']
+  spec.email     = 'scott@rightscale.com'
+  spec.homepage  = 'https://github.com/rightscale/right_popen'
+  if is_windows
+    spec.platform = 'x86-mswin32-60'
+  else
+    spec.platform  = Gem::Platform::RUBY
+  end
+  spec.summary   = 'Provides a platform-independent popen implementation'
+  spec.has_rdoc = true
+  spec.rdoc_options = ["--main", "README.rdoc", "--title", "RightPopen"]
+  spec.extra_rdoc_files = ["README.rdoc"]
+  spec.required_ruby_version = '>= 1.8.6'
+  spec.rubyforge_project = %q{right_popen}
+
+  spec.description = <<-EOF
+RightPopen allows running external processes aynchronously while still
+capturing their standard and error outputs. It relies on EventMachine for most
+of its internal mechanisms. The Linux implementation is valid for any Linux
+platform but there is also a native implementation for Windows platforms.
+EOF
+
+  if is_windows
+    extension_dir = "ext,"
+  else
+    extension_dir = ""
+  end
+  candidates = Dir.glob("{#{extension_dir}lib,spec}/**/*") +
+               ["LICENSE", "README.rdoc", "Rakefile", "right_popen.gemspec"]
+  candidates = candidates.delete_if do |item|
+    item.include?("Makefile") || item.include?(".obj") || item.include?(".pdb") || item.include?(".def") || item.include?(".exp") || item.include?(".lib")
+  end
+  candidates = candidates.delete_if do |item|
+    if is_windows
+      item.include?("/linux/")
+    else
+      item.include?("/win32/")
+    end
+  end
+  spec.files = candidates.sort!
+
+  # Current implementation doesn't support > 0.12.8, but support any patched 0.12.8.x versions.
+  spec.add_runtime_dependency(%q<eventmachine>, [">= 0.12.8", "< 0.12.9"])
+  if is_windows
+    spec.add_runtime_dependency(%q<win32-process>, [">= 0.6.1"])
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+   Gem.manage_gems if Gem::RubyGemsVersion.to_f < 1.0
+   Gem::Builder.new(spec).build
+end

data/spec/produce_mixed_output.rb

@@ -0,0 +1,8 @@
+count = ARGV[0] ? ARGV[0].to_i : 1
+
+count.times do |i|
+  $stderr.puts "stderr #{i}" if 0 == i % 10
+  $stdout.puts "stdout #{i}"
+end
+
+exit 99

data/spec/produce_output.rb

@@ -0,0 +1,2 @@
+$stdout.puts ARGV[0]
+$stderr.puts ARGV[1]

data/spec/produce_status.rb

@@ -0,0 +1 @@
+exit ARGV[0].to_i

data/spec/produce_stderr_only.rb

@@ -0,0 +1,5 @@
+count = ARGV[0] ? ARGV[0].to_i : 1
+
+count.times do |i|
+  $stderr.puts "stderr #{i}"
+end

data/spec/produce_stdout_only.rb

@@ -0,0 +1,5 @@
+count = ARGV[0] ? ARGV[0].to_i : 1
+
+count.times do |i|
+  $stdout.puts "stdout #{i}"
+end

data/spec/right_popen_spec.rb

@@ -0,0 +1,125 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+require 'right_popen'
+
+RUBY_CMD         = 'ruby'
+STANDARD_MESSAGE = 'Standard message'
+ERROR_MESSAGE    = 'Error message'
+EXIT_STATUS      = 146
+
+# manually bump count up for more aggressive multi-processor testing, lessen
+# for a quick smoke test
+LARGE_OUTPUT_COUNTER = 1000
+
+describe 'RightScale::popen3' do
+
+  module RightPopenSpec
+
+    class Runner
+      def initialize
+        @done        = false
+        @output_text = ''
+        @error_text  = ''
+        @status      = nil
+      end
+
+      attr_reader :output_text, :error_text, :status
+
+      def run_right_popen(command)
+        EM.next_tick do
+          RightScale.popen3(command, self, :on_read_stdout, :on_read_stderr, :on_exit)
+        end
+        EM.run do
+          timer = EM::PeriodicTimer.new(0.1) do
+            if @done
+              timer.cancel
+              EM.stop
+            end
+          end
+        end
+      end
+
+      def on_read_stdout(data)
+        @output_text << data
+      end
+
+      def on_read_stderr(data)
+        @error_text << data
+      end
+
+      def on_exit(status)
+        @status = status
+        @done = true
+      end
+    end
+
+  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 = RightPopenSpec::Runner.new
+    runner.run_right_popen(command)
+    runner.status.exitstatus.should == 0
+    runner.output_text.should == STANDARD_MESSAGE + "\n"
+    runner.error_text.should == ERROR_MESSAGE + "\n"
+  end
+
+  it 'should return the right status' do
+    command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_status.rb'))}\" #{EXIT_STATUS}"
+    runner = RightPopenSpec::Runner.new
+    runner.run_right_popen(command)
+    runner.status.exitstatus.should == EXIT_STATUS
+    runner.output_text.should == ''
+    runner.error_text.should == ''
+  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 = RightPopenSpec::Runner.new
+    runner.run_right_popen(command)
+    runner.status.exitstatus.should == 0
+
+    results = ''
+    count.times do |i|
+      results << "stdout #{i}\n"
+    end
+    runner.output_text.should == results
+    runner.error_text.should == ''
+  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 = RightPopenSpec::Runner.new
+    runner.run_right_popen(command)
+    runner.status.exitstatus.should == 0
+
+    results = ''
+    count.times do |i|
+      results << "stderr #{i}\n"
+    end
+    runner.error_text.should == results
+    runner.output_text.should == ''
+  end
+
+  it 'should preserve the integrity of stdout and stderr despite interleaving' do
+    count = LARGE_OUTPUT_COUNTER
+    command = "\"#{RUBY_CMD}\" \"#{File.expand_path(File.join(File.dirname(__FILE__), 'produce_mixed_output.rb'))}\" #{count}"
+    runner = RightPopenSpec::Runner.new
+    runner.run_right_popen(command)
+    runner.status.exitstatus.should == 99
+
+    results = ''
+    count.times do |i|
+      results << "stdout #{i}\n"
+    end
+    runner.output_text.should == results
+
+    results = ''
+    count.times do |i|
+      (results << "stderr #{i}\n") if 0 == i % 10
+    end
+    runner.error_text.should == results
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'rubygems'
+$:.push File.join(File.dirname(__FILE__), '..', 'lib')

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: right_popen
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- Scott Messier
+- Raphael Simon
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-27 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.12.8
+    - - <
+      - !ruby/object:Gem::Version 
+        version: 0.12.9
+    version: 
+description: |
+  RightPopen allows running external processes aynchronously while still
+  capturing their standard and error outputs. It relies on EventMachine for most
+  of its internal mechanisms. The Linux implementation is valid for any Linux
+  platform but there is also a native implementation for Windows platforms.
+
+email: scott@rightscale.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/linux/right_popen.rb
+- lib/right_popen.rb
+- right_popen.gemspec
+- spec/produce_mixed_output.rb
+- spec/produce_output.rb
+- spec/produce_status.rb
+- spec/produce_stderr_only.rb
+- spec/produce_stdout_only.rb
+- spec/right_popen_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: https://github.com/rightscale/right_popen
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+- --title
+- RightPopen
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.6
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: right_popen
+rubygems_version: 1.3.2
+signing_key: 
+specification_version: 3
+summary: Provides a platform-independent popen implementation
+test_files: []
+