right_popen 1.0.11 → 1.0.16

data/Rakefile

@@ -1,14 +1,37 @@
 require 'rubygems'
+require 'bundler'
 require 'fileutils'
 require 'rake'
 require 'rake/clean'
-require 'rake/testtask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
 require 'rbconfig'
 
+def list_spec_files
+  list = Dir['spec/**/*_spec.rb']
+  list.delete_if { |path| path.include?('/linux/') } if RUBY_PLATFORM =~ /mswin/
+  list
+end
+
 include Config
 
+Bundler::GemHelper.install_tasks
+
+# == Gem == #
+
+gemtask = Rake::GemPackageTask.new(Gem::Specification.load("right_popen.gemspec")) do |package|
+  package.package_dir = ENV['PACKAGE_DIR'] || 'pkg'
+  package.need_zip = true
+  package.need_tar = true
+end
+
+directory gemtask.package_dir
+
+CLEAN.include(gemtask.package_dir)
+
 desc "Clean any build files for right_popen"
-task :clean do
+task :win_clean do
   if RUBY_PLATFORM =~ /mswin/
     if File.exists?('ext/Makefile')
       Dir.chdir('ext') do
@@ -18,6 +41,7 @@ task :clean do
     rm 'lib/win32/right_popen.so' if File.file?('lib/win32/right_popen.so')
   end
 end
+task :clean => :win_clean
 
 desc "Build right_popen (but don't install it)"
 task :build => [:clean] do
@@ -32,15 +56,14 @@ task :build => [:clean] do
 end
 
 desc "Build a binary gem"
-task :gem => [:build] do
-   Dir["*.gem"].each { |gem| rm gem }
-   ruby 'right_popen.gemspec'
-end
+task :gem => [:build]
 
 desc 'Install the right_popen library as a gem'
 task :install_gem => [:gem] do
-   file = Dir["*.gem"].first
-   sh "gem install #{file}"
+  Dir.chdir(File.dirname(__FILE__)) do
+     file = Dir["pkg/*.gem"].first
+     sh "gem install #{file}"
+  end
 end
 
 desc 'Uninstalls and reinstalls the right_popen library as a gem'
@@ -49,7 +72,44 @@ task :reinstall_gem do
    sh "rake install_gem"
 end
 
-desc 'Runs all spec tests'
-task :spec do
-  sh "spec spec/*_spec.rb"
+# == Unit Tests == #
+
+task :specs => :spec
+
+desc "Run unit tests"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = list_spec_files
+end
+
+desc "Run unit tests with RCov"
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.spec_files = list_spec_files
+  t.rcov = true
+end
+
+desc "Print Specdoc for unit tests"
+Spec::Rake::SpecTask.new(:doc) do |t|
+   t.spec_opts = ["--format", "specdoc", "--dry-run"]
+   t.spec_files = list_spec_files
+end
+
+# == Documentation == #
+
+desc "Generate API documentation to doc/rdocs/index.html"
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'doc/rdocs'
+  rd.main = 'README.rdoc'
+  rd.rdoc_files.include 'README.rdoc', "lib/**/*.rb"
+
+  rd.options << '--inline-source'
+  rd.options << '--line-numbers'
+  rd.options << '--all'
+  rd.options << '--fileboxes'
+  rd.options << '--diagram'
+end
+
+# == Emacs integration == #
+desc "Rebuild TAGS file"
+task :tags do
+  sh "rtags -R lib spec"
 end

data/lib/right_popen.rb

@@ -26,9 +26,9 @@
 # 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'))
+  require File.expand_path(File.join(File.dirname(__FILE__), 'right_popen', 'win32', 'right_popen'))
 else
-  require File.expand_path(File.join(File.dirname(__FILE__), 'linux', 'right_popen'))
+  require File.expand_path(File.join(File.dirname(__FILE__), 'right_popen', 'linux', 'right_popen'))
 end
 
 module RightScale
@@ -55,13 +55,13 @@ module RightScale
   # options[:exit_handler](String):: Exit handler method name, optional
   #
   # === Returns
-  # true:: Always returns true
+  # true:: always true
   def self.popen3(options)
     raise "EventMachine reactor must be started" unless EM.reactor_running?
     raise "Missing command" unless options[:command]
     raise "Missing target" unless options[:target] || !options[:stdout_handler] && !options[:stderr_handler] && !options[:exit_handler] && !options[:pid_handler]
-    RightScale.popen3_imp(options)
-    true
+    GC.start # To garbage collect open file descriptors from passed executions
+    return RightScale.popen3_imp(options)
   end
 
 end

data/lib/right_popen/linux/accumulator.rb

@@ -0,0 +1,117 @@
+#--  -*- mode: ruby; encoding: utf-8 -*-
+# Copyright: Copyright (c) 2011 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
+    class Accumulator
+      READ_CHUNK_SIZE = 4096
+
+      def initialize(process, inputs, read_callbacks, outputs, write_callbacks)
+        @process = process
+        @inputs = inputs
+        @outputs = outputs
+        null = Proc.new {}
+        @reads = {}
+        @writes = {}
+        inputs.zip(read_callbacks).each do |pair|
+          input, callback = pair
+          @reads[input] = callback
+        end
+        outputs.zip(write_callbacks).each do |pair|
+          output, callback = pair
+          @writes[output] = callback
+        end
+        @writebuffers = {}
+        @status = nil
+      end
+
+      def tick(sleep_time = 0.1)
+        return true unless @process.status.nil?
+
+        @process.status = status = ::Process.waitpid2(@process.pid, ::Process::WNOHANG)
+
+        inputs = @inputs.dup
+        outputs = @outputs.dup
+        ready = nil
+        while ready.nil?
+          begin
+            # in theory, we should note "exceptional conditions" and
+            # permit procs for those, too.  In practice there are only
+            # two times when exceptional conditions occur: out of band
+            # data in TCP connections and "packet mode" for
+            # pseudoterminals.  We care about neither of these,
+            # therefore ignore exceptional conditions.
+            ready = IO.select(inputs, outputs, nil, sleep_time)
+          rescue Errno::EAGAIN, Errno::EINTR
+          end
+        end unless inputs.empty? && outputs.empty?
+
+        ready[0].each do |fdes|
+          if fdes.eof?
+            fdes.close
+            @inputs.delete(fdes)
+          else
+            chunk = fdes.readpartial(READ_CHUNK_SIZE)
+            @reads[fdes].call(chunk) if @reads[fdes]
+          end
+        end unless ready.nil? || ready[0].nil?
+        ready[1].each do |fdes|
+          buffered = @writebuffers[fdes]
+          buffered = @writes[fdes].call if @writes[fdes] if buffered.nil? || buffered.empty?
+          if buffered.nil?
+            fdes.close
+            @outputs.delete(fdes)
+          elsif !buffered.empty?
+            begin
+              amount = fdes.write_nonblock buffered
+              @writebuffers[fdes] = buffered[amount..-1]
+            rescue Errno::EPIPE
+              # subprocess closed the pipe; fine.
+              fdes.close
+              @outputs.delete(fdes)
+            end
+          end
+        end unless ready.nil? || ready[1].nil?
+
+        return !@process.status.nil?
+      end
+
+      def number_waiting_on
+        @inputs.size + @outputs.size
+      end
+
+      def cleanup
+        @inputs.each {|p| p.close unless p.closed? }
+        @outputs.each {|p| p.close unless p.closed? }
+        @process.status = ::Process.waitpid2(@process.pid) if @process.status.nil?
+      end
+
+      def run_to_completion(sleep_time=0.1)
+        until tick(sleep_time)
+          break if number_waiting_on == 0
+        end
+        cleanup
+      end
+    end
+  end
+end

data/lib/right_popen/linux/process.rb

@@ -0,0 +1,148 @@
+#--  -*- mode: ruby; encoding: utf-8 -*-
+# Copyright: Copyright (c) 2011 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.
+#++
+
+require 'etc'
+
+module RightScale
+  module RightPopen
+    class Process
+      attr_reader :pid, :stdin, :stdout, :stderr, :status_fd
+      attr_accessor :status
+      
+      def initialize(parameters={})
+        parameters[:locale] = true unless parameters.has_key?(:locale)
+        @parameters = parameters
+        @status_fd = nil
+      end
+      
+      def fork(cmd)
+        @cmd = cmd
+        stdin_r, stdin_w = IO.pipe
+        stdout_r, stdout_w = IO.pipe
+        stderr_r, stderr_w = IO.pipe
+        status_r, status_w = IO.pipe
+
+        [stdin_r, stdin_w, stdout_r, stdout_w,
+         stderr_r, stderr_w, status_r, status_w].each {|fdes| fdes.sync = true}
+
+        @pid = Kernel::fork do
+          begin
+            stdin_w.close
+            STDIN.reopen stdin_r
+
+            stdout_r.close
+            STDOUT.reopen stdout_w
+
+            stderr_r.close
+            STDERR.reopen stderr_w
+
+            status_r.close
+            status_w.fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC)
+            
+            if group = get_group
+              ::Process.egid = group
+              ::Process.gid = group
+            end
+
+            if user = get_user
+              ::Process.euid = user
+              ::Process.uid = user
+            end
+
+            Dir.chdir(@parameters[:directory]) if @parameters[:directory]
+
+            ENV["LC_ALL"] = "C" if @parameters[:locale]
+          
+            @parameters[:environment].each do |key,value|
+              ENV[key.to_s] = value.to_s
+            end if @parameters[:environment]
+
+            File.umask(get_umask) if @parameters[:umask]
+
+            if cmd.kind_of?(Array)
+              exec(*cmd)
+            else
+              exec("sh", "-c", cmd)
+            end
+            raise 'forty-two' 
+          rescue Exception => e
+            Marshal.dump(e, status_w)
+          end
+          status_w.close
+          exit!
+        end
+
+        stdin_r.close
+        stdout_w.close
+        stderr_w.close
+        status_w.close
+        @stdin = stdin_w
+        @stdout = stdout_r
+        @stderr = stderr_r
+        @status_fd = status_r
+      end
+
+      def wait_for_exec
+        begin
+          e = Marshal.load @status_fd
+          # thus meaning that the process failed to exec...
+          @stdin.close
+          @stdout.close
+          @stderr.close
+          raise(Exception === e ? e : "unknown failure!")
+        rescue EOFError
+          # thus meaning that the process did exec and we can continue.
+        ensure
+          @status_fd.close
+        end
+      end
+
+      private
+
+      def get_user
+        user = @parameters[:user] || nil
+        unless user.kind_of?(Integer)
+          user = Etc.getpwnam(user).uid if user
+        end
+        user
+      end
+
+      def get_group
+        group = @parameters[:group] || nil
+        unless group.kind_of?(Integer)
+          group = Etc.getgrnam(group).gid if group
+        end
+        group
+      end
+
+      def get_umask
+        if @parameters[:umask].respond_to?(:oct)
+          value = @parameters[:umask].oct
+        else
+          value = @parameters[:umask].to_i
+        end
+        value & 007777
+      end
+    end
+  end
+end

data/lib/right_popen/linux/right_popen.rb

@@ -0,0 +1,170 @@
+#--
+# 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'
+require 'eventmachine'
+require File.expand_path(File.join(File.dirname(__FILE__), "process"))
+require File.expand_path(File.join(File.dirname(__FILE__), "accumulator"))
+require File.expand_path(File.join(File.dirname(__FILE__), "utilities"))
+
+module RightScale
+  # ensure uniqueness of handler to avoid confusion.
+  raise "#{StatusHandler.name} is already defined" if defined?(StatusHandler)
+
+  module StatusHandler
+    def initialize(file_handle)
+      # Voodoo to make sure that Ruby doesn't gc the file handle
+      # (closing the stream) before we're done with it.  No, oddly
+      # enough EventMachine is not good about holding on to this
+      # itself.
+      @handle = file_handle
+      @data = ""
+    end
+
+    def receive_data(data)
+      @data << data
+    end
+
+    def drain_and_close
+      begin
+        while ready = IO.select([@handle], nil, nil, 0)
+          break if @handle.eof?
+          data = @handle.readpartial(4096)
+          receive_data(data)
+        end
+      rescue Errno::EBADF
+      rescue EOFError
+      end
+      close_connection
+    end
+
+    def unbind
+      if @data.size > 0
+        e = Marshal.load @data
+        raise (Exception === e ? e : "unknown failure: saw #{e} on status channel")
+      end
+    end
+  end
+  
+  # ensure uniqueness of handler to avoid confusion.
+  raise "#{PipeHandler.name} is already defined" if defined?(PipeHandler)
+
+  module PipeHandler
+    def initialize(file_handle, target, handler)
+      # Voodoo to make sure that Ruby doesn't gc the file handle
+      # (closing the stream) before we're done with it.  No, oddly
+      # enough EventMachine is not good about holding on to this
+      # itself.
+      @handle = file_handle
+      @target = target
+      @handler = handler
+    end
+
+    def receive_data(data)
+      @target.method(@handler).call(data) if @handler
+    end
+
+    def drain_and_close
+      begin
+        while ready = IO.select([@handle], nil, nil, 0)
+          break if @handle.eof?
+          data = @handle.readpartial(4096)
+          receive_data(data)
+        end
+      rescue Errno::EBADF
+      rescue EOFError
+      end
+      close_connection
+    end
+  end
+
+  # ensure uniqueness of handler to avoid confusion.
+  raise "#{InputHandler.name} is already defined" if defined?(InputHandler)
+
+  module InputHandler
+    def initialize(file_handle, string)
+      # Voodoo to make sure that Ruby doesn't gc the file handle
+      # (closing the stream) before we're done with it.  No, oddly
+      # enough EventMachine is not good about holding on to this
+      # itself.
+      @handle = file_handle
+      @string = string
+    end
+
+    def post_init
+      send_data(@string) if @string
+      close_connection_after_writing
+    end
+
+    def drain_and_close
+      close_connection
+    end
+  end
+
+  # Forks process to run given command asynchronously, hooking all three
+  # standard streams of the child process.
+  #
+  # === Parameters
+  # options[:pid_handler](Symbol):: Token for pid handler method name.
+  #
+  # See RightScale.popen3
+  def self.popen3_imp(options)
+    # note GC.start moved to common popen3 entry method for use by both windows and linux.
+    EM.next_tick do
+      process = RightPopen::Process.new(:environment => options[:environment] || {})
+      process.fork(options[:command])
+
+      status_handler = EM.attach(process.status_fd, StatusHandler, process.status_fd)
+      stderr_handler = EM.attach(process.stderr, PipeHandler, process.stderr, options[:target],
+                                 options[:stderr_handler])
+      stdout_handler = EM.attach(process.stdout, PipeHandler, process.stdout, options[:target],
+                                 options[:stdout_handler])
+      stdin_handler = EM.attach(process.stdin, InputHandler, process.stdin, options[:input])
+
+      options[:target].method(options[:pid_handler]).call(process.pid) if
+        options.key? :pid_handler
+
+      wait_timer = EM::PeriodicTimer.new(1) do
+        value = ::Process.waitpid2(process.pid, Process::WNOHANG)
+        unless value.nil?
+          begin
+            ignored, status = value
+            options[:target].method(options[:exit_handler]).call(status) if
+              options[:exit_handler]
+          ensure
+            stdin_handler.drain_and_close
+            stdout_handler.drain_and_close
+            stderr_handler.drain_and_close
+            status_handler.drain_and_close
+            wait_timer.cancel
+          end
+        end
+      end
+    end
+    true
+  end
+end