right_popen 1.0.21-x86-mswin32-60 → 1.1.3-x86-mswin32-60

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/lib/right_popen/win32/popen3_async.rb

@@ -0,0 +1,258 @@
+#--
+# Copyright (c) 2009-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.
+#++
+
+require 'rubygems'
+require 'eventmachine'
+
+require ::File.expand_path(::File.join(::File.dirname(__FILE__), 'process'))
+
+module RightScale::RightPopen
+
+  # ensure uniqueness of handler to avoid confusion.
+  raise "#{StdInHandler.name} is already defined" if defined?(StdInHandler)
+
+  # Eventmachine callback handler for stdin stream
+  module StdInHandler
+
+    # === Parameters
+    # options[:input](String):: Input to be streamed into child process stdin
+    # stream_in(IO):: Standard input stream.
+    def initialize(options, stream_in)
+      @stream_in = stream_in
+      @input = options[:input]
+    end
+
+    # Eventmachine callback asking for more to write
+    # Send input and close stream in
+    def post_init
+      if @input
+        send_data(@input)
+        close_connection_after_writing
+        @input = nil
+      else
+        close_connection
+      end
+    end
+
+  end
+
+  # ensure uniqueness of handler to avoid confusion.
+  raise "#{StdOutHandler.name} is already defined" if defined?(StdOutHandler)
+
+  # Provides an eventmachine callback handler for the stdout stream.
+  module StdOutHandler
+
+    # === Parameters
+    # @param [Process] process that was executed
+    # @param [Object] target defining handler methods to be called
+    # @param [Connector] stderr_eventable EM object representing stderr handler.
+    # @param [IO] stream_out as standard output stream
+    def initialize(process, target, stderr_eventable, stream_out)
+      @process = process
+      @target = target
+      @stderr_eventable = stderr_eventable
+      @stream_out = stream_out
+      @status = nil
+    end
+
+    # Callback from EM to asynchronously read the stdout stream. Note that this
+    # callback mechanism is deprecated after EM v0.12.8 but the win32 EM code
+    # has never advanced beyond that point.
+    def notify_readable
+      data = ::RightScale::RightPopen.async_read(@stream_out)
+      receive_data(data) if (data && data.length > 0)
+      detach unless data
+    end
+
+    # Callback from EM to receive data, which we also use to handle the
+    # asynchronous data we read ourselves.
+    def receive_data(data)
+      @target.stdout_handler(data)
+    end
+
+    # Override of Connection.get_status() for Windows implementation.
+    def get_status
+      unless @status
+        @status = @process.wait_for_exit_status
+      end
+      return @status
+    end
+
+    # Callback from EM to unbind.
+    def unbind
+      # We force the stderr watched handler to go away so that
+      # we don't end up with a broken pipe
+      @stderr_eventable.force_detach if @stderr_eventable
+      @target.timeout_handler if @process.timer_expired?
+      @target.size_limit_handler if @process.size_limit_exceeded?
+      @target.exit_handler(get_status)
+      @stream_out.close
+    end
+  end
+
+  # ensure uniqueness of handler to avoid confusion.
+  raise "#{StdErrHandler.name} is already defined" if defined?(StdErrHandler)
+
+  # Provides an eventmachine callback handler for the stderr stream.
+  module StdErrHandler
+
+    # === Parameters
+    # @param [Object] target defining handler methods to be called
+    # @param [IO] stream_err as standard error stream
+    def initialize(target, stream_err)
+      @target = target
+      @stderr_handler = target.method(:stderr_handler)
+      @stream_err = stream_err
+      @unbound = false
+    end
+
+    # Callback from EM to asynchronously read the stderr stream. Note that this
+    # callback mechanism is deprecated after EM v0.12.8
+    def notify_readable
+      # call native win32 implementation for async_read
+      data = ::RightScale::RightPopen.async_read(@stream_err)
+      receive_data(data) if (data && data.length > 0)
+      detach unless data
+    end
+
+    # Callback from EM to receive data, which we also use to handle the
+    # asynchronous data we read ourselves.
+    def receive_data(data)
+      @stderr_handler.call(data)
+    end
+
+    # Callback from EM to unbind.
+    def unbind
+      @unbound = true
+      @stream_err.close
+    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
+
+  # See RightScale.popen3_async for details
+  def self.popen3_async_impl(cmd, target, options)
+    # always create eventables on the main EM thread by using next_tick. this
+    # prevents synchronization problems between EM threads.
+    ::EM.next_tick do
+      process = nil
+      begin
+        # create process.
+        process = ::RightScale::RightPopen::Process.new(options)
+        process.spawn(cmd, target)
+
+        # close input immediately unless streaming. the EM implementation is
+        # flawed so it is important to not create an eventable for the input
+        # stream unless required. the issue stems from EM thinking that file
+        # handles and socket handles come from the same pool in the stdio
+        # libraries; in Linux they come from the same pool, in Windows they don't.
+        process.stdin.close unless options[:input]
+
+        # attach handlers to event machine and let it monitor incoming data. the
+        # streams aren't used directly by the connectors except that they are
+        # closed on unbind.
+        stderr_eventable = ::EM.watch(process.stderr, ::RightScale::RightPopen::StdErrHandler, target, process.stderr) do |c|
+          c.notify_readable = true
+        end
+        ::EM.watch(process.stdout, ::RightScale::RightPopen::StdOutHandler, process, target, stderr_eventable, process.stdout) do |c|
+          c.notify_readable = true
+          target.pid_handler(process.pid)
+
+          # initial watch callback.
+          #
+          # note that we cannot abandon async watch; callback needs to interrupt
+          # in this case
+          target.watch_handler(process)
+        end
+        if options[:input]
+          ::EM.attach(process.stdin, ::RightScale::RightPopen::StdInHandler, options, process.stdin)
+        end
+
+        # create a periodic watcher only if needed in the win32 async case because
+        # the exit handler is tied to EM eventable detachment.
+        #
+        # TEAL FIX: does this logic need to differ from Linux or can they share
+        # the same code? they probably differ because the mswin32 implementation
+        # of EM stopped many versions back.
+        if process.needs_watching?
+          ::EM.next_tick do
+            watch_process(process, 0.1, target)
+          end
+        end
+      rescue
+        # we can't raise from the main EM thread or it will stop EM.
+        # the spawn method will signal the exit handler but not the
+        # pid handler in this case since there is no pid. any action
+        # (logging, etc.) associated with the failure will have to be
+        # driven by the exit handler.
+        target.exit_handler(process.status) rescue nil if target && process
+      end
+    end
+
+    # note that control returns to the caller, but the launched cmd continues
+    # running and sends output to the handlers. the caller is not responsible
+    # for waiting for the process to terminate or closing streams as the
+    # watched eventables will handle this automagically. notification will be
+    # sent to the exit_handler on process termination.
+    true
+  end
+
+  # watches process for interrupt criteria. doubles the wait time up to a
+  # maximum of 1 second for next wait.
+  #
+  # === Parameters
+  # @param [Process] process that was run
+  # @param [Numeric] wait_time as seconds to wait before checking status
+  # @param [Object] target for handler calls
+  #
+  # === Return
+  # true:: Always return true
+  def self.watch_process(process, wait_time, target)
+    ::EM::Timer.new(wait_time) do
+      begin
+        if process.alive?
+          if process.timer_expired? || process.size_limit_exceeded?
+            process.interrupt
+          else
+            # cannot abandon async watch; callback needs to interrupt in this case
+            target.watch_handler(process)
+          end
+          watch_process(process, [wait_time * 2, 1].min, target)
+        end
+      rescue
+        # we can't raise from the main EM thread or it will stop EM.
+        # the spawn method will signal the exit handler but not the
+        # pid handler in this case since there is no pid. any action
+        # (logging, etc.) associated with the failure will have to be
+        # driven by the exit handler.
+      end
+    end
+    true
+  end
+
+end