childprocess 0.9.0

data/childprocess.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "childprocess/version"
+
+Gem::Specification.new do |s|
+  s.name        = "childprocess"
+  s.version     = ChildProcess::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Jari Bakken", "Eric Kessler"]
+  s.email       = ["morrow748@gmail.com"]
+  s.homepage    = "http://github.com/enkessler/childprocess"
+  s.summary     = %q{A simple and reliable solution for controlling external programs running in the background on any Ruby / OS combination.}
+  s.description = %q{This gem aims at being a simple and reliable solution for controlling external programs running in the background on any Ruby / OS combination.}
+
+  s.rubyforge_project = "childprocess"
+  s.license           = 'MIT'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "ffi", "~> 1.0", ">= 1.0.11"
+
+  s.add_development_dependency "rspec", "~> 3.0"
+  s.add_development_dependency "yard", "~> 0.0"
+  s.add_development_dependency 'rake', '< 12.0'
+  s.add_development_dependency 'coveralls', '< 1.0'
+end
+
+

data/lib/childprocess.rb

@@ -0,0 +1,205 @@
+require 'childprocess/version'
+require 'childprocess/errors'
+require 'childprocess/abstract_process'
+require 'childprocess/abstract_io'
+require "fcntl"
+require 'logger'
+
+module ChildProcess
+
+  @posix_spawn = false
+
+  class << self
+    attr_writer :logger
+
+    def new(*args)
+      case os
+      when :macosx, :linux, :solaris, :bsd, :cygwin, :aix
+        if posix_spawn?
+          Unix::PosixSpawnProcess.new(args)
+        elsif jruby?
+          JRuby::Process.new(args)
+        else
+          Unix::ForkExecProcess.new(args)
+        end
+      when :windows
+        Windows::Process.new(args)
+      else
+        raise Error, "unsupported platform #{platform_name.inspect}"
+      end
+    end
+    alias_method :build, :new
+
+    def logger
+      return @logger if defined?(@logger) and @logger
+
+      @logger = Logger.new($stderr)
+      @logger.level = $DEBUG ? Logger::DEBUG : Logger::INFO
+
+      @logger
+    end
+
+    def platform
+      if RUBY_PLATFORM == "java"
+        :jruby
+      elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == "ironruby"
+        :ironruby
+      else
+        os
+      end
+    end
+
+    def platform_name
+      @platform_name ||= "#{arch}-#{os}"
+    end
+
+    def unix?
+      !windows?
+    end
+
+    def linux?
+      os == :linux
+    end
+
+    def jruby?
+      platform == :jruby
+    end
+
+    def windows?
+      os == :windows
+    end
+
+    def posix_spawn?
+      enabled = @posix_spawn || %w[1 true].include?(ENV['CHILDPROCESS_POSIX_SPAWN'])
+      return false unless enabled
+
+      require 'ffi'
+      begin
+        require "childprocess/unix/platform/#{ChildProcess.platform_name}"
+      rescue LoadError
+        raise ChildProcess::MissingPlatformError
+      end
+
+      require "childprocess/unix/lib"
+      require 'childprocess/unix/posix_spawn_process'
+
+      true
+    rescue ChildProcess::MissingPlatformError => ex
+      warn_once ex.message
+      false
+    end
+
+    #
+    # Set this to true to enable experimental use of posix_spawn.
+    #
+
+    def posix_spawn=(bool)
+      @posix_spawn = bool
+    end
+
+    def os
+      @os ||= (
+        require "rbconfig"
+        host_os = RbConfig::CONFIG['host_os'].downcase
+
+        case host_os
+        when /linux/
+          :linux
+        when /darwin|mac os/
+          :macosx
+        when /mswin|msys|mingw32/
+          :windows
+        when /cygwin/
+          :cygwin
+        when /solaris|sunos/
+          :solaris
+        when /bsd|dragonfly/
+          :bsd
+        when /aix/
+          :aix
+        else
+          raise Error, "unknown os: #{host_os.inspect}"
+        end
+      )
+    end
+
+    def arch
+      @arch ||= (
+        host_cpu = RbConfig::CONFIG['host_cpu'].downcase
+        case host_cpu
+        when /i[3456]86/
+          if workaround_older_macosx_misreported_cpu?
+            # Workaround case: older 64-bit Darwin Rubies misreported as i686
+            "x86_64"
+          else
+            "i386"
+          end
+        when /amd64|x86_64/
+          "x86_64"
+        when /ppc|powerpc/
+          "powerpc"
+        else
+          host_cpu
+        end
+      )
+    end
+
+    #
+    # By default, a child process will inherit open file descriptors from the
+    # parent process. This helper provides a cross-platform way of making sure
+    # that doesn't happen for the given file/io.
+    #
+
+    def close_on_exec(file)
+      if file.respond_to?(:close_on_exec=)
+        file.close_on_exec = true
+      elsif file.respond_to?(:fcntl) && defined?(Fcntl::FD_CLOEXEC)
+        file.fcntl Fcntl::F_SETFD, Fcntl::FD_CLOEXEC
+
+        if jruby? && posix_spawn?
+          # on JRuby, the fcntl call above apparently isn't enough when
+          # we're launching the process through posix_spawn.
+          fileno = JRuby.posix_fileno_for(file)
+          Unix::Lib.fcntl fileno, Fcntl::F_SETFD, Fcntl::FD_CLOEXEC
+        end
+      elsif windows?
+        Windows::Lib.dont_inherit file
+      else
+        raise Error, "not sure how to set close-on-exec for #{file.inspect} on #{platform_name.inspect}"
+      end
+    end
+
+    private
+
+    def warn_once(msg)
+      @warnings ||= {}
+
+      unless @warnings[msg]
+        @warnings[msg] = true
+        logger.warn msg
+      end
+    end
+
+    # Workaround: detect the situation that an older Darwin Ruby is actually
+    # 64-bit, but is misreporting cpu as i686, which would imply 32-bit.
+    #
+    # @return [Boolean] `true` if:
+    #   (a) on Mac OS X
+    #   (b) actually running in 64-bit mode
+    def workaround_older_macosx_misreported_cpu?
+      os == :macosx && is_64_bit?
+    end
+
+    # @return [Boolean] `true` if this Ruby represents `1` in 64 bits (8 bytes).
+    def is_64_bit?
+      1.size == 8
+    end
+
+  end # class << self
+end # ChildProcess
+
+require 'jruby' if ChildProcess.jruby?
+
+require 'childprocess/unix'    if ChildProcess.unix?
+require 'childprocess/windows' if ChildProcess.windows?
+require 'childprocess/jruby'   if ChildProcess.jruby?

data/lib/childprocess/abstract_io.rb

@@ -0,0 +1,36 @@
+module ChildProcess
+  class AbstractIO
+    attr_reader :stderr, :stdout, :stdin
+
+    def inherit!
+      @stdout = STDOUT
+      @stderr = STDERR
+    end
+
+    def stderr=(io)
+      check_type io
+      @stderr = io
+    end
+
+    def stdout=(io)
+      check_type io
+      @stdout = io
+    end
+
+    #
+    # @api private
+    #
+
+    def _stdin=(io)
+      check_type io
+      @stdin = io
+    end
+
+    private
+
+    def check_type(io)
+      raise SubclassResponsibility, "check_type"
+    end
+
+  end
+end

data/lib/childprocess/abstract_process.rb

@@ -0,0 +1,192 @@
+module ChildProcess
+  class AbstractProcess
+    POLL_INTERVAL = 0.1
+
+    attr_reader :exit_code
+
+    #
+    # Set this to true if you do not care about when or if the process quits.
+    #
+    attr_accessor :detach
+
+    #
+    # Set this to true if you want to write to the process' stdin (process.io.stdin)
+    #
+    attr_accessor :duplex
+
+    #
+    # Modify the child's environment variables
+    #
+    attr_reader :environment
+
+    #
+    # Set the child's current working directory.
+    #
+    attr_accessor :cwd
+
+    #
+    # Set this to true to make the child process the leader of a new process group
+    #
+    # This can be used to make sure that all grandchildren are killed
+    # when the child process dies.
+    #
+    attr_accessor :leader
+
+    #
+    # Create a new process with the given args.
+    #
+    # @api private
+    # @see ChildProcess.build
+    #
+
+    def initialize(args)
+      unless args.all? { |e| e.kind_of?(String) }
+        raise ArgumentError, "all arguments must be String: #{args.inspect}"
+      end
+
+      @args        = args
+      @started     = false
+      @exit_code   = nil
+      @io          = nil
+      @cwd         = nil
+      @detach      = false
+      @duplex      = false
+      @leader      = false
+      @environment = {}
+    end
+
+    #
+    # Returns a ChildProcess::AbstractIO subclass to configure the child's IO streams.
+    #
+
+    def io
+      raise SubclassResponsibility, "io"
+    end
+
+    #
+    # @return [Integer] the pid of the process after it has started
+    #
+
+    def pid
+      raise SubclassResponsibility, "pid"
+    end
+
+    #
+    # Launch the child process
+    #
+    # @return [AbstractProcess] self
+    #
+
+    def start
+      launch_process
+      @started = true
+
+      self
+    end
+
+    #
+    # Forcibly terminate the process, using increasingly harsher methods if possible.
+    #
+    # @param [Integer] timeout (3) Seconds to wait before trying the next method.
+    #
+
+    def stop(timeout = 3)
+      raise SubclassResponsibility, "stop"
+    end
+
+    #
+    # Block until the process has been terminated.
+    #
+    # @return [Integer] The exit status of the process
+    #
+
+    def wait
+      raise SubclassResponsibility, "wait"
+    end
+
+    #
+    # Did the process exit?
+    #
+    # @return [Boolean]
+    #
+
+    def exited?
+      raise SubclassResponsibility, "exited?"
+    end
+
+    #
+    # Has the process started?
+    #
+    # @return [Boolean]
+    #
+
+    def started?
+      @started
+    end
+
+    #
+    # Is this process running?
+    #
+    # @return [Boolean]
+    #
+
+    def alive?
+      started? && !exited?
+    end
+
+    #
+    # Returns true if the process has exited and the exit code was not 0.
+    #
+    # @return [Boolean]
+    #
+
+    def crashed?
+      exited? && @exit_code != 0
+    end
+
+    #
+    # Wait for the process to exit, raising a ChildProcess::TimeoutError if
+    # the timeout expires.
+    #
+
+    def poll_for_exit(timeout)
+      log "polling #{timeout} seconds for exit"
+
+      end_time = Time.now + timeout
+      until (ok = exited?) || Time.now > end_time
+        sleep POLL_INTERVAL
+      end
+
+      unless ok
+        raise TimeoutError, "process still alive after #{timeout} seconds"
+      end
+    end
+
+    private
+
+    def launch_process
+      raise SubclassResponsibility, "launch_process"
+    end
+
+    def detach?
+      @detach
+    end
+
+    def duplex?
+      @duplex
+    end
+
+    def leader?
+      @leader
+    end
+
+    def log(*args)
+      ChildProcess.logger.debug "#{self.inspect} : #{args.inspect}"
+    end
+
+    def assert_started
+      raise Error, "process not started" unless started?
+    end
+
+  end # AbstractProcess
+end # ChildProcess