subprocess 1.1.0 → 1.5.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03feecd6b5ca0a66f4c795071be9ed48d4801ac8735e69660ff7e87b05f1e47d
+  data.tar.gz: 0dad63e1568ca3a477471b98b912ee0528963d80d1ee8646813b2efa7429d429
+SHA512:
+  metadata.gz: 0d5cc41f0a7d716cb87c6e70c25b4892905b12d2c55727e29af281bc8e66f46be68a6a76fc263ac1ed1a8fd709288b3101dcd0d2ed19aac36c94d9de133ea171
+  data.tar.gz: 25b247b27b30ce8dc4cf98670adb415f82bc4e4ce64ba5e410307ba194efd516c13af19ded736568a2e95ab88bacda16a46b626230be45f2a948db7e7876ad7e

data/README.md

@@ -1,15 +1,8 @@
-Subprocess
-==========
+# Subprocess [![Build Status](https://travis-ci.org/stripe/subprocess.svg?branch=master)](https://travis-ci.org/stripe/subprocess) [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/stripe/subprocess/Subprocess)
 
 ![Jacques Cousteau Submarine](http://i.imgur.com/lmej24F.jpg)
 
-A port of Python's excellent subprocess module to Ruby.
-
-Many thanks to [Bram Swenson][bram], the author of the old [subprocess][old]
-gem, for graciously letting us use the name.
-
-[bram]: https://github.com/bramswenson
-[old]: https://github.com/bramswenson/subprocess
+A solid subprocess library for ruby, inspired by python's.
 
 Installation
 ------------
@@ -22,20 +15,10 @@ You can also build `subprocess` from source by running:
 
     $ gem build subprocess.gemspec
 
-
 Usage
 -----
 
-Most of the documentation for Python's [subprocess][python] module applies
-equally well to this gem as well. While there are a few places when our
-semantics differs from Python's, users of the Python module should largely feel
-at home using `subprocess`. We have attempted to [document][rubydoc] all of the
-differences, but if we have missed something, please file an issue.
-
-[python]: http://docs.python.org/library/subprocess.html
-[rubydoc]: http://rubydoc.info/github/stripe/subprocess
-
-A few examples:
+Full documentation is on [RubyDoc][rubydoc]. A few examples:
 
 ```ruby
 require 'subprocess'
@@ -72,3 +55,21 @@ http://upload.wikimedia.org/wikipedia/commons/3/3e/Unshorn_alpaca_grazing.jpg
   EMAIL
 end
 ```
+
+Most of the documentation for Python's [subprocess][python] module applies
+equally well to this gem as well. While there are a few places when our
+semantics differs from Python's, users of the Python module should largely feel
+at home using `subprocess`. We have attempted to [document][rubydoc] all of the
+differences, but if we have missed something, please file an issue.
+
+[python]: http://docs.python.org/library/subprocess.html
+[rubydoc]: http://rubydoc.info/github/stripe/subprocess/Subprocess
+
+Acknowledgements
+----------------
+
+Many thanks to [Bram Swenson][bram], the author of the old [subprocess][old]
+gem, for graciously letting us use the name.
+
+[bram]: https://github.com/bramswenson
+[old]: https://github.com/bramswenson/subprocess

data/lib/subprocess.rb

@@ -16,7 +16,13 @@ module Subprocess
 
   # An alias for `Process.new`. Mostly here to better emulate the Python API.
   #
+  # @param [Array<String>] cmd See {Process#initialize}
+  # @param [Hash] opts See {Process#initialize}
+  # @yield [process] See {Process#initialize}
+  # @yieldparam process [Process] See {Process#initialize}
   # @return [Process] A process with the given arguments
+  #
+  # @see Process#initialize
   def self.popen(cmd, opts={}, &blk)
     Process.new(cmd, opts, &blk)
   end
@@ -28,9 +34,14 @@ module Subprocess
   #   fills up, as neither file descriptor will be read from. To avoid this, use
   #   {Process#communicate} from a passed block.
   #
+  # @param [Array<String>] cmd See {Process#initialize}
+  # @param [Hash] opts See {Process#initialize}
+  # @yield [process] See {Process#initialize}
+  # @yieldparam process [Process] See {Process#initialize}
+  #
   # @return [::Process::Status] The exit status of the process
   #
-  # @see {Process#initialize}
+  # @see Process#initialize
   def self.call(cmd, opts={}, &blk)
     Process.new(cmd, opts, &blk).wait
   end
@@ -58,11 +69,16 @@ module Subprocess
   #   fills up, as neither file descriptor will be read from. To avoid this, use
   #   {Process#communicate} from a passed block.
   #
+  # @param [Array<String>] cmd See {Process#initialize}
+  # @param [Hash] opts See {Process#initialize}
+  # @yield [process] See {Process#initialize}
+  # @yieldparam process [Process] See {Process#initialize}
+  #
   # @raise [NonZeroExit] if the process returned a non-zero exit status (i.e.,
   #   was terminated with an error or was killed by a signal)
   # @return [::Process::Status] The exit status of the process
   #
-  # @see {Process#initialize}
+  # @see Process#initialize
   def self.check_call(cmd, opts={}, &blk)
     status = Process.new(cmd, opts, &blk).wait
     raise NonZeroExit.new(cmd, status) unless status.success?
@@ -70,16 +86,21 @@ module Subprocess
   end
 
   # Like {Subprocess::check_call}, but return the contents of `stdout`, much
-  # like `Kernel#system`.
+  # like {::Kernel#system}.
   #
   # @example Get the system load
   #   system_load = Subprocess.check_output(['uptime']).split(' ').last(3)
   #
+  # @param [Array<String>] cmd See {Process#initialize}
+  # @param [Hash] opts See {Process#initialize}
+  # @yield [process] See {Process#initialize}
+  # @yieldparam process [Process] See {Process#initialize}
+  #
   # @raise [NonZeroExit] if the process returned a non-zero exit status (i.e.,
   #   was terminated with an error or was killed by a signal)
   # @return [String] The contents of `stdout`
   #
-  # @see {Process#initialize}
+  # @see Process#initialize
   def self.check_output(cmd, opts={}, &blk)
     opts[:stdout] = PIPE
     child = Process.new(cmd, opts, &blk)
@@ -107,17 +128,7 @@ module Subprocess
         # been according to the usual exit status convention
         sig_num = status.exitstatus - 128
 
-        # sigh, why is ruby so silly
-        if Signal.respond_to?(:signame)
-          # ruby 2.0 way
-          sig_name = Signal.signame(sig_num)
-        elsif Signal.list.respond_to?(:key)
-          # ruby 1.9 way
-          sig_name = Signal.list.key(sig_num)
-        else
-          # ruby 1.8 way
-          sig_name = Signal.list.index(sig_num)
-        end
+        sig_name = Signal.signame(sig_num)
 
         if sig_name
           parts << "(maybe SIG#{sig_name})"
@@ -140,16 +151,17 @@ module Subprocess
 
   # Error class representing a process's abnormal exit.
   class NonZeroExit < StandardError
-    # @!attribute [r] command
-    #   @note This is intended only for use in user-facing error messages. In
-    #     particular, no shell quoting of any sort is performed when
-    #     constructing this string, meaning that blindly running it in a shell
-    #     might have different semantics than the original command.
-    #   @return [String] The command and arguments for the process that exited
-    #     abnormally.
-    # @!attribute [r] status
-    #   @return [::Process::Status] The Ruby status object returned by `waitpid`
-    attr_reader :command, :status
+    # @note This is intended only for use in user-facing error messages. In
+    #   particular, no shell quoting of any sort is performed when
+    #   constructing this string, meaning that blindly running it in a shell
+    #   might have different semantics than the original command.
+    #
+    # @return [String] The command and arguments for the process that exited
+    #   abnormally.
+    attr_reader :command
+
+    # @return [::Process::Status] The Ruby status object returned by `waitpid`
+    attr_reader :status
 
     # Return an instance of {NonZeroExit}.
     #
@@ -171,42 +183,63 @@ module Subprocess
     end
   end
 
+  # Error class representing a timeout during a call to `communicate`
+  class CommunicateTimeout < StandardError
+    # @return [String] Content read from stdout before the timeout
+    attr_reader :stdout
+
+    # @return [String] Content read from stderr before the timeout
+    attr_reader :stderr
+
+    # @param [Array<String>] cmd
+    # @param [String] stdout
+    # @param [String] stderr
+    def initialize(cmd, stdout, stderr)
+      @stdout = stdout
+      @stderr = stderr
+
+      super("Timeout communicating with `#{cmd.join(' ')}`")
+    end
+  end
+
   # A child process. The preferred way of spawning a subprocess is through the
   # functions on {Subprocess} (especially {Subprocess::check_call} and
   # {Subprocess::check_output}).
   class Process
-    # @!attribute [r] stdin
-    #   @return [IO] The `IO` that is connected to this process's `stdin`.
-    # @!attribute [r] stdout
-    #   @return [IO] The `IO` that is connected to this process's `stdout`.
-    # @!attribute [r] stderr
-    #   @return [IO] The `IO` that is connected to this process's `stderr`.
-    attr_reader :stdin, :stdout, :stderr
-
-    # @!attribute [r] command
-    #   @return [Array<String>] The command this process was invoked with.
-    # @!attribute [r] pid
-    #   @return [Fixnum] The process ID of the spawned process.
-    # @!attribute [r] status
-    #   @return [::Process::Status] The exit status code of the process. Only
-    #     set after the process has exited.
-    attr_reader :command, :pid, :status
+    # @return [IO] The `IO` that is connected to this process's `stdin`.
+    attr_reader :stdin
+
+    # @return [IO] The `IO` that is connected to this process's `stdout`.
+    attr_reader :stdout
+
+    # @return [IO] The `IO` that is connected to this process's `stderr`.
+    attr_reader :stderr
+
+    # @return [Array<String>] The command this process was invoked with.
+    attr_reader :command
+
+    # @return [Integer] The process ID of the spawned process.
+    attr_reader :pid
+
+    # @return [::Process::Status] The exit status code of the process. Only
+    #   set after the process has exited.
+    attr_reader :status
 
     # Create a new process.
     #
     # @param [Array<String>] cmd The command to run and its arguments (in the
     #   style of an `argv` array). Unlike Python's subprocess module, `cmd`
-    #   cannnot be a String.
+    #   cannot be a String.
     #
-    # @option opts [IO, Fixnum, String, Subprocess::PIPE, nil] :stdin The `IO`,
+    # @option opts [IO, Integer, String, Subprocess::PIPE, nil] :stdin The `IO`,
     #   file descriptor number, or file name to use for the process's standard
     #   input. If the magic value {Subprocess::PIPE} is passed, a new pipe will
     #   be opened.
-    # @option opts [IO, Fixnum, String, Subprocess::PIPE, nil] :stdout The `IO`,
+    # @option opts [IO, Integer, String, Subprocess::PIPE, nil] :stdout The `IO`,
     #   file descriptor number, or file name to use for the process's standard
     #   output. If the magic value {Subprocess::PIPE} is passed, a pipe will be
     #   opened and attached to the process.
-    # @option opts [IO, Fixnum, String, Subprocess::PIPE, Subprocess::STDOUT,
+    # @option opts [IO, Integer, String, Subprocess::PIPE, Subprocess::STDOUT,
     #   nil] :stderr The `IO`, file descriptor number, or file name to use for
     #   the process's standard error. If the special value {Subprocess::PIPE} is
     #   passed, a pipe will be opened and attached to the process. If the
@@ -217,16 +250,15 @@ module Subprocess
     #   child process.
     # @option opts [Hash<String, String>] :env The environment to use in the
     #   child process.
-    # @option opts [Array<Fixnum>] :retain_fds An array of file descriptor
+    # @option opts [Array<Integer>] :retain_fds An array of file descriptor
     #   numbers that should not be closed before executing the child process.
     #   Note that, unlike Python (which has :close_fds defaulting to false), all
     #   file descriptors not specified here will be closed.
+    # @option opts [Hash] :exec_opts A hash that will be merged into the options
+    #   hash of the call to {::Kernel#exec}.
     #
     # @option opts [Proc] :preexec_fn A function that will be called in the
-    #   child process immediately before executing `cmd`. Note: we don't
-    #   actually close file descriptors, but instead set them to auto-close on
-    #   `exec` (using `FD_CLOEXEC`), so your application will probably continue
-    #   to behave as expected.
+    #   child process immediately before executing `cmd`.
     #
     # @yield [process] Yields the just-spawned {Process} to the optional block.
     #   This occurs after all of {Process}'s error handling has been completed,
@@ -234,7 +266,8 @@ module Subprocess
     #   in conjunction with {Subprocess::check_call}.
     # @yieldparam process [Process] The process that was just spawned.
     def initialize(cmd, opts={}, &blk)
-      raise ArgumentError, "cmd must be an Array" unless Array === cmd
+      raise ArgumentError, "cmd must be an Array of strings" unless Array === cmd
+      raise ArgumentError, "cmd cannot be empty" if cmd.empty?
 
       @command = cmd
 
@@ -253,69 +286,6 @@ module Subprocess
 
       @pid = fork do
         begin
-          require 'fcntl'
-
-          FileUtils.cd(opts[:cwd]) if opts[:cwd]
-
-          # The only way to mark an fd as CLOEXEC in ruby is to create an IO
-          # object wrapping it. In 1.8, however, there's no way to create that
-          # IO without it believing it owns the underlying fd, s.t. it will
-          # close the fd if the IO is GC'd before the exec. Since we don't want
-          # that, we stash a list of these IO objects to prevent them from
-          # getting GC'd, since we are about to exec, which will clean
-          # everything up anyways.
-          fds = []
-
-          # We have a whole ton of file descriptors that we don't want leaking
-          # into the child. Set them all to close when we exec away.
-          #
-          # Ruby 1.9+ note: exec has a :close_others argument (and 2.0 closes
-          # FDs by default). When we stop supporting Ruby 1.8, all of this can
-          # go away.
-          if File.directory?("/dev/fd")
-            # On many modern UNIX-y systems, we can perform an optimization by
-            # looking through /dev/fd, which is a sparse listing of all the
-            # descriptors we have open. This allows us to avoid an expensive
-            # linear scan.
-            Dir.foreach("/dev/fd") do |file|
-              fd = file.to_i
-              if file.start_with?('.') || fd < 3 || retained_fds.include?(fd)
-                next
-              end
-              begin
-                fds << mark_fd_cloexec(fd)
-              rescue Errno::EBADF
-                # The fd might have been closed by now; that's peaceful.
-              end
-            end
-          else
-            # This is the big hammer. There's not really a good way of doing
-            # this comprehensively across all platforms without just trying them
-            # all. We only go up to the soft limit here. If you've been messing
-            # with the soft limit, we might miss a few. Also, on OSX (perhaps
-            # BSDs in general?), where the soft limit means something completely
-            # different.
-            special = [@child_stdin, @child_stdout, @child_stderr].compact
-            special = Hash[special.map { |f| [f.fileno, f] }]
-            3.upto(::Process.getrlimit(::Process::RLIMIT_NOFILE).first) do |fd|
-              next if retained_fds.include?(fd)
-              begin
-                # I don't know why we need to do this, but OSX started freaking
-                # out when trying to dup2 below if FD_CLOEXEC had been set on a
-                # fresh IO instance referring to the same underlying file
-                # descriptor as what we were trying to dup2 from.
-                if special[fd]
-                  special[fd].fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC)
-                else
-                  fds << mark_fd_cloexec(fd)
-                end
-              rescue Errno::EBADF # Ignore FDs that don't exist
-              end
-            end
-          end
-
-          # dup2 the correct descriptors into place. Note that this clears the
-          # FD_CLOEXEC flag on the new file descriptors (but not the old ones).
           ::STDIN.reopen(@child_stdin) if @child_stdin
           ::STDOUT.reopen(@child_stdout) if @child_stdout
           if opts[:stderr] == STDOUT
@@ -327,25 +297,44 @@ module Subprocess
           # Set up a new environment if we're requested to do so.
           if opts[:env]
             ENV.clear
-            ENV.update(opts[:env])
+            begin
+              ENV.update(opts[:env])
+            rescue TypeError => e
+              raise ArgumentError, "`env` option must be a hash where all keys and values are strings (#{e})"
+            end
           end
 
           # Call the user back, maybe?
-          opts[:preexec_fn].call if opts[:preexec_fn]
-
-          # Ruby 1.8's exec is really stupid--there's no way to specify that
-          # you want to exec a single thing *without* performing shell
-          # expansion. So this is the next best thing.
-          args = cmd
-          if cmd.length == 1
-            args = ["'" + cmd[0].gsub("'", "\\'") + "'"]
+          if opts[:preexec_fn]
+            if opts[:cwd]
+              Dir.chdir(opts[:cwd], &opts[:preexec_fn])
+            else
+              opts[:preexec_fn].call
+            end
           end
+
+          options = {close_others: true}.merge(opts.fetch(:exec_opts, {}))
           if opts[:retain_fds]
-            redirects = {}
-            retained_fds.each { |fd| redirects[fd] = fd }
-            args << redirects
+            retained_fds.each { |fd| options[fd] = fd }
+          end
+          if opts[:cwd]
+            # We use the chdir option to `exec` since wrapping the
+            # `exec` in a Dir.chdir block caused these sporadic errors on macOS:
+            # Too many open files - getcwd (Errno::EMFILE)
+            options[:chdir] = opts[:cwd]
+          end
+
+          begin
+            # Ruby's Kernel#exec will call an exec(3) variant if called with two
+            # or more arguments, but when called with just a single argument will
+            # spawn a subshell with that argument as the command. Since we always
+            # want to call exec(3), we use the third exec form, which passes a
+            # [cmdname, argv0] array as its first argument and never invokes a
+            # subshell.
+            exec([cmd[0], cmd[0]], *cmd[1..-1], options)
+          rescue TypeError => e
+            raise ArgumentError, "cmd must be an Array of strings (#{e})"
           end
-          exec(*args)
 
         rescue Exception => e
           # Dump all errors up to the parent through the control socket
@@ -360,12 +349,13 @@ module Subprocess
       # Meanwhile, in the parent process...
 
       # First, let's close some things we shouldn't have access to
-      [@child_stdin, @child_stdout, @child_stderr, control_w].each do |fd|
-        fd.close unless fd.nil?
-      end
+      @child_stdin.close if our_fd?(opts[:stdin])
+      @child_stdout.close if our_fd?(opts[:stdout])
+      @child_stderr.close if our_fd?(opts[:stderr])
+      control_w.close
 
       # Any errors during the spawn process? We'll get past this point when the
-      # child execs and the OS closes control_w because of the FD_CLOEXEC
+      # child execs and the OS closes control_w
       begin
         e = Marshal.load(control_r)
         e = "Unknown Failure" unless e.is_a?(Exception) || e.is_a?(String)
@@ -407,7 +397,7 @@ module Subprocess
     #   condition (`EOFError` or `EPIPE`).
     def drain_fd(fd, buf=nil)
       loop do
-        tmp = fd.read_nonblock(4096)
+        tmp = fd.read_nonblock(4096).force_encoding(fd.external_encoding)
         buf << tmp unless buf.nil?
       end
     rescue EOFError, Errno::EPIPE
@@ -418,40 +408,48 @@ module Subprocess
       false
     end
 
-    # Write the (optional) input to the process's `stdin`. Also, read (and
-    # buffer in memory) the contents of `stdout` and `stderr`. Do this all using
-    # `IO::select`, so we don't deadlock due to full pipe buffers.
+    # Write the (optional) input to the process's `stdin` and read the contents of
+    # `stdout` and `stderr`. If a block is provided, stdout and stderr are yielded as they
+    # are read. Otherwise they are buffered in memory and returned when the process
+    # exits. Do this all using `IO::select`, so we don't deadlock due to full pipe
+    # buffers.
     #
     # This is only really useful if you set some of `:stdin`, `:stdout`, and
     # `:stderr` to {Subprocess::PIPE}.
     #
     # @param [String] input A string to feed to the child's standard input.
-    # @return [Array<String>] An array of two elements: the data read from the
+    # @param [Numeric] timeout_s Raise {Subprocess::CommunicateTimeout} if communicate
+    #   does not finish after timeout_s seconds.
+    # @yieldparam [String] stdout Data read from stdout since the last yield
+    # @yieldparam [String] stderr Data read from stderr since the last yield
+    # @return [Array(String, String), nil] An array of two elements: the data read from the
     #   child's standard output and standard error, respectively.
-    def communicate(input=nil)
+    #   Returns nil if a block is provided.
+    def communicate(input=nil, timeout_s=nil)
       raise ArgumentError if !input.nil? && @stdin.nil?
 
       stdout, stderr = "", ""
+
       input = input.dup unless input.nil?
 
       @stdin.close if (input.nil? || input.empty?) && !@stdin.nil?
 
-      self_read, self_write = IO.pipe
-      self.class.catching_sigchld(pid, self_write) do
-        wait_r = [@stdout, @stderr, self_read].compact
+      timeout_at = Time.now + timeout_s if timeout_s
+
+      self.class.catching_sigchld(pid) do |global_read, self_read|
+        wait_r = [@stdout, @stderr, self_read, global_read].compact
         wait_w = [input && @stdin].compact
-        loop do
-          ready_r, ready_w = select(wait_r, wait_w)
-
-          # If the child exits, we still have to be sure to read any data left
-          # in the pipes. So we poll the child, drain all the pipes, and *then*
-          # check @status.
-          #
-          # It's very important that we do not call poll between draining the
-          # pipes and checking @status. If we did, we open a race condition
-          # where the child writes to stdout and exits in that brief window,
-          # causing us to lose that data.
-          poll
+        done = false
+        while !done
+          # If the process has exited, we want to drain any remaining output before returning
+          if poll
+            ready_r = wait_r - [self_read, global_read]
+            ready_w = []
+            done = true
+          else
+            ready_r, ready_w = select_until(wait_r, wait_w, [], timeout_at)
+            raise CommunicateTimeout.new(@command, stdout, stderr) if ready_r.nil?
+          end
 
           if ready_r.include?(@stdout)
             if drain_fd(@stdout, stdout)
@@ -465,6 +463,13 @@ module Subprocess
             end
           end
 
+          if ready_r.include?(global_read)
+            if drain_fd(global_read)
+              raise "Unexpected internal error -- someone closed the global self-pipe!"
+            end
+            self.class.wakeup_sigchld
+          end
+
           if ready_r.include?(self_read)
             if drain_fd(self_read)
               raise "Unexpected internal error -- someone closed our self-pipe!"
@@ -472,10 +477,24 @@ module Subprocess
           end
 
           if ready_w.include?(@stdin)
+            written = 0
             begin
               written = @stdin.write_nonblock(input)
             rescue EOFError # Maybe I shouldn't catch this...
             rescue Errno::EINTR
+            rescue IO::WaitWritable
+              # On OS X, a pipe can raise EAGAIN even after select indicates
+              # that it is writable. Once the process consumes from the pipe,
+              # the next write should succeed and we should make forward progress.
+              # Until then, treat this as not writing any bytes and continue looping.
+              # For details see: https://github.com/stripe/subprocess/pull/22
+              nil
+            rescue Errno::EPIPE
+              # The other side of the pipe closed before we could
+              # write all of our input. This can happen if the
+              # process exits prematurely.
+              @stdin.close
+              wait_w.delete(@stdin)
             end
             input[0...written] = ''
             if input.empty?
@@ -484,29 +503,41 @@ module Subprocess
             end
           end
 
-          break if @status
-
-          # If there's nothing left to wait for, we're done!
-          break if wait_r.length == 0 && wait_w.length == 0
+          if block_given? && !(stderr.empty? && stdout.empty?)
+            yield stdout, stderr
+            stdout, stderr = "", ""
+          end
         end
       end
 
       wait
 
-      [stdout, stderr]
+      if block_given?
+        nil
+      else
+        [stdout, stderr]
+      end
     end
 
     # Does exactly what it says on the box.
     #
-    # @param [String, Symbol, Fixnum] signal The signal to send to the child
+    # @param [String, Symbol, Integer] signal The signal to send to the child
     #   process. Accepts all the same arguments as Ruby's built-in
     #   {::Process::kill}, for instance a string like "INT" or "SIGINT", or a
     #   signal number like 2.
+    #
+    # @return [Integer] See {::Process.kill}
+    #
+    # @see ::Process.kill
     def send_signal(signal)
       ::Process.kill(signal, pid)
     end
 
     # Sends `SIGTERM` to the process.
+    #
+    # @return [Integer] See {send_signal}
+    #
+    # @see send_signal
     def terminate
       send_signal("TERM")
     end
@@ -517,16 +548,17 @@ module Subprocess
     # "mine" is only non-nil in the case of a pipe (in fact, we just return a
     # list of length one, since ruby will unpack nils from missing list items).
     #
-    # If you pass either an IO or an Integer (i.e., a raw file descriptor), a
-    # private copy of it will be made using `#dup`.
+    # @param [IO, Integer, String, nil] fd
+    # @param [String] mode
+    # @return [Array<IO>]
     def parse_fd(fd, mode)
       fds = case fd
       when PIPE
         IO.pipe
       when IO
-        [fd.dup]
+        [fd]
       when Integer
-        [IO.new(fd, mode).dup]
+        [IO.new(fd, mode)]
       when String
         [File.open(fd, mode)]
       when nil
@@ -538,42 +570,106 @@ module Subprocess
       mode == 'r' ? fds : fds.reverse
     end
 
-    def mark_fd_cloexec(fd)
-      io = IO.new(fd)
-      io.fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC)
-      io
-    rescue ArgumentError => e
-      # Ruby maintains a self-pipe for thread interrupts, but it handles closing
-      # it on forks/execs
-      raise unless e.message == "The given fd is not accessible because RubyVM reserves it"
+    # The pair to parse_fd, returns whether or not the file descriptor was
+    # opened by us (and therefore should be closed by us).
+    #
+    # @param [IO, Integer, String, nil] fd
+    # @return [Boolean]
+    def our_fd?(fd)
+      case fd
+      when PIPE, String
+        true
+      else
+        false
+      end
+    end
+
+    # Call IO.select timing out at Time `timeout_at`. If `timeout_at` is nil, never times out.
+    #
+    # @param [Array<IO>, nil] read_array
+    # @param [Array<IO>, nil] write_array
+    # @param [Array<IO>, nil] err_array
+    # @param [Integer, Float, nil] timeout_at
+    # @return [Array<Array<IO>>, nil]
+    def select_until(read_array, write_array, err_array, timeout_at)
+      if !timeout_at
+        return IO.select(read_array, write_array, err_array)
+      end
+
+      remaining = (timeout_at - Time.now)
+      return nil if remaining <= 0
+
+      IO.select(read_array, write_array, err_array, remaining)
     end
 
     @sigchld_mutex = Mutex.new
     @sigchld_fds = {}
     @sigchld_old_handler = nil
+    @sigchld_global_write = nil
+    @sigchld_global_read = nil
+    @sigchld_pipe_pid = nil
+
+    # @return [void]
+    def self.handle_sigchld
+      # We'd like to just notify everything in `@sigchld_fds`, but
+      # ruby signal handlers are not executed atomically with respect
+      # to other Ruby threads, so reading it is racy. We can't grab
+      # `@sigchld_mutex`, because signal execution blocks the main
+      # thread, and so we'd deadlock if the main thread currently
+      # holds it.
+      #
+      # Instead, we keep a long-lived notify self-pipe that we select
+      # on inside `communicate`, and we task `communicate` with
+      # grabbing the lock and fanning out the wakeups.
+      begin
+        @sigchld_global_write.write_nonblock("\x00")
+      rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+        nil # ignore
+      end
+    end
 
     # Wake up everyone. We can't tell who we should wake up without `wait`ing,
     # and we want to let the process itself do that. In practice, we're not
     # likely to have that many in-flight subprocesses, so this is probably not a
     # big deal.
-    def self.handle_sigchld
-      @sigchld_fds.values.each do |fd|
-        begin
-          fd.write_nonblock("\x00")
-        rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+    # @return [void]
+    def self.wakeup_sigchld
+      @sigchld_mutex.synchronize do
+        @sigchld_fds.values.each do |fd|
+          begin
+            fd.write_nonblock("\x00")
+          rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+            # If the pipe is full, the other end will be woken up
+            # regardless when it next reads, so it's fine to skip the
+            # write (the pipe is a wakeup channel, and doesn't contain
+            # meaningful data).
+          end
         end
       end
     end
 
+    # @param [Integer] pid
+    # @param [IO] fd
+    # @return [void]
     def self.register_pid(pid, fd)
       @sigchld_mutex.synchronize do
         @sigchld_fds[pid] = fd
         if @sigchld_fds.length == 1
+          if @sigchld_global_write.nil? || @sigchld_pipe_pid != ::Process.pid
+            # Check the PID so that if we fork we will re-open the
+            # pipe. It's important that a fork parent and child don't
+            # share this pipe, because if they do they risk stealing
+            # each others' wakeups.
+            @sigchld_pipe_pid = ::Process.pid
+            @sigchld_global_read, @sigchld_global_write = IO.pipe
+          end
           @sigchld_old_handler = Signal.trap('SIGCHLD') {handle_sigchld}
         end
       end
     end
 
+    # @param [Integer] pid
+    # @return [void]
     def self.unregister_pid(pid)
       @sigchld_mutex.synchronize do
         if @sigchld_fds.length == 1
@@ -583,11 +679,17 @@ module Subprocess
       end
     end
 
-    def self.catching_sigchld(pid, fd)
-      register_pid(pid, fd)
-      yield
-    ensure
-      unregister_pid(pid)
+    # @param [Integer] pid
+    # @return [void]
+    def self.catching_sigchld(pid)
+      IO.pipe do |self_read, self_write|
+        begin
+          register_pid(pid, self_write)
+          yield @sigchld_global_read, self_read
+        ensure
+          unregister_pid(pid)
+        end
+      end
     end
   end
 end

data/lib/subprocess/version.rb

@@ -1,3 +1,3 @@
 module Subprocess
-  VERSION = '1.1.0'
+  VERSION = '1.5.4'
 end

data/rbi/subprocess.rbi

@@ -0,0 +1,312 @@
+# typed: strong
+
+# THIS FILE IS AUTOGENERATED. DO NOT EDIT.
+# To regenerate from YARD comments:
+#
+#     bundle exec rake sord
+#
+# A Ruby clone of Python's subprocess module.
+#
+# @see http://docs.python.org/2/library/subprocess.html
+module ::Subprocess
+  PIPE = T.let(-1, T.untyped)
+  STDOUT = T.let(-2, T.untyped)
+  VERSION = T.let('1.5.4', T.untyped)
+
+  # An alias for `Process.new`. Mostly here to better emulate the Python API.
+  #
+  # _@param_ `cmd` — See {Process#initialize}
+  #
+  # _@param_ `opts` — See {Process#initialize}
+  #
+  # _@return_ — A process with the given arguments
+  #
+  # _@see_ `Process#initialize`
+  sig { params(cmd: T::Array[String], opts: T::Hash[T.untyped, T.untyped], blk: T.nilable(T.proc.params(process: Process).void)).returns(Process) }
+  def self.popen(cmd, opts = {}, &blk); end
+
+  # Call and wait for the return of a given process.
+  #
+  # _@param_ `cmd` — See {Process#initialize}
+  #
+  # _@param_ `opts` — See {Process#initialize}
+  #
+  # _@return_ — The exit status of the process
+  #
+  # _@note_ — If you call this function with `:stdout => PIPE` or `:stderr => PIPE`,
+  # this function will block indefinitely as soon as the OS's pipe buffer
+  # fills up, as neither file descriptor will be read from. To avoid this, use
+  # {Process#communicate} from a passed block.
+  #
+  # _@see_ `Process#initialize`
+  sig { params(cmd: T::Array[String], opts: T::Hash[T.untyped, T.untyped], blk: T.nilable(T.proc.params(process: Process).void)).returns(::Process::Status) }
+  def self.call(cmd, opts = {}, &blk); end
+
+  # Like {Subprocess::call}, except raise a {NonZeroExit} if the process did not
+  # terminate successfully.
+  #
+  # _@param_ `cmd` — See {Process#initialize}
+  #
+  # _@param_ `opts` — See {Process#initialize}
+  #
+  # _@return_ — The exit status of the process
+  #
+  # Grep a file for a string
+  # ```ruby
+  # Subprocess.check_call(%W{grep -q llama ~/favorite_animals})
+  # ```
+  #
+  # Communicate with a child process
+  # ```ruby
+  # Subprocess.check_call(%W{sendmail -t}, :stdin => Subprocess::PIPE) do |p|
+  #   p.communicate <<-EMAIL
+  # From: alpaca@example.com
+  # To: llama@example.com
+  # Subject: I am so fluffy.
+  #
+  # SO FLUFFY!
+  # http://upload.wikimedia.org/wikipedia/commons/3/3e/Unshorn_alpaca_grazing.jpg
+  #   EMAIL
+  # end
+  # ```
+  #
+  # _@note_ — If you call this function with `:stdout => PIPE` or `:stderr => PIPE`,
+  # this function will block indefinitely as soon as the OS's pipe buffer
+  # fills up, as neither file descriptor will be read from. To avoid this, use
+  # {Process#communicate} from a passed block.
+  #
+  # _@see_ `Process#initialize`
+  sig { params(cmd: T::Array[String], opts: T::Hash[T.untyped, T.untyped], blk: T.nilable(T.proc.params(process: Process).void)).returns(::Process::Status) }
+  def self.check_call(cmd, opts = {}, &blk); end
+
+  # Like {Subprocess::check_call}, but return the contents of `stdout`, much
+  # like {::Kernel#system}.
+  #
+  # _@param_ `cmd` — See {Process#initialize}
+  #
+  # _@param_ `opts` — See {Process#initialize}
+  #
+  # _@return_ — The contents of `stdout`
+  #
+  # Get the system load
+  # ```ruby
+  # system_load = Subprocess.check_output(['uptime']).split(' ').last(3)
+  # ```
+  #
+  # _@see_ `Process#initialize`
+  sig { params(cmd: T::Array[String], opts: T::Hash[T.untyped, T.untyped], blk: T.nilable(T.proc.params(process: Process).void)).returns(String) }
+  def self.check_output(cmd, opts = {}, &blk); end
+
+  # Print a human readable interpretation of a process exit status.
+  #
+  # _@param_ `status` — The status returned by `waitpid2`.
+  #
+  # _@param_ `convert_high_exit` — Whether to convert exit statuses greater than 128 into the usual convention for exiting after trapping a signal. (e.g. many programs will exit with status 130 after receiving a SIGINT / signal 2.)
+  #
+  # _@return_ — Text interpretation
+  sig { params(status: ::Process::Status, convert_high_exit: T::Boolean).returns(String) }
+  def self.status_to_s(status, convert_high_exit = true); end
+
+  # Error class representing a process's abnormal exit.
+  class NonZeroExit < StandardError
+    # Return an instance of {NonZeroExit}.
+    #
+    # _@param_ `cmd` — The command that returned a non-zero status.
+    #
+    # _@param_ `status` — The status returned by `waitpid`.
+    sig { params(cmd: T::Array[String], status: ::Process::Status).void }
+    def initialize(cmd, status); end
+
+    # _@return_ — The command and arguments for the process that exited
+    # abnormally.
+    #
+    # _@note_ — This is intended only for use in user-facing error messages. In
+    # particular, no shell quoting of any sort is performed when
+    # constructing this string, meaning that blindly running it in a shell
+    # might have different semantics than the original command.
+    sig { returns(String) }
+    attr_reader :command
+
+    # _@return_ — The Ruby status object returned by `waitpid`
+    sig { returns(::Process::Status) }
+    attr_reader :status
+  end
+
+  # Error class representing a timeout during a call to `communicate`
+  class CommunicateTimeout < StandardError
+    # _@param_ `cmd`
+    #
+    # _@param_ `stdout`
+    #
+    # _@param_ `stderr`
+    sig { params(cmd: T::Array[String], stdout: String, stderr: String).void }
+    def initialize(cmd, stdout, stderr); end
+
+    # _@return_ — Content read from stdout before the timeout
+    sig { returns(String) }
+    attr_reader :stdout
+
+    # _@return_ — Content read from stderr before the timeout
+    sig { returns(String) }
+    attr_reader :stderr
+  end
+
+  # A child process. The preferred way of spawning a subprocess is through the
+  # functions on {Subprocess} (especially {Subprocess::check_call} and
+  # {Subprocess::check_output}).
+  class Process
+    # Create a new process.
+    #
+    # _@param_ `cmd` — The command to run and its arguments (in the style of an `argv` array). Unlike Python's subprocess module, `cmd` cannot be a String.
+    sig { params(cmd: T::Array[String], opts: T::Hash[T.untyped, T.untyped], blk: T.nilable(T.proc.params(process: Process).void)).void }
+    def initialize(cmd, opts = {}, &blk); end
+
+    # Poll the child, setting (and returning) its status. If the child has not
+    # terminated, return nil and exit immediately
+    #
+    # _@return_ — The exit status of the process
+    sig { returns(T.nilable(::Process::Status)) }
+    def poll; end
+
+    # Wait for the child to return, setting and returning the status of the
+    # child.
+    #
+    # _@return_ — The exit status of the process
+    sig { returns(::Process::Status) }
+    def wait; end
+
+    # Do nonblocking reads from `fd`, appending all data read into `buf`.
+    #
+    # _@param_ `fd` — The file to read from.
+    #
+    # _@param_ `buf` — A buffer to append the read data to.
+    #
+    # _@return_ — Whether `fd` was closed due to an exceptional
+    # condition (`EOFError` or `EPIPE`).
+    sig { params(fd: IO, buf: T.nilable(String)).returns(T::Boolean) }
+    def drain_fd(fd, buf = nil); end
+
+    # Write the (optional) input to the process's `stdin` and read the contents of
+    # `stdout` and `stderr`. If a block is provided, stdout and stderr are yielded as they
+    # are read. Otherwise they are buffered in memory and returned when the process
+    # exits. Do this all using `IO::select`, so we don't deadlock due to full pipe
+    # buffers.
+    #
+    # This is only really useful if you set some of `:stdin`, `:stdout`, and
+    # `:stderr` to {Subprocess::PIPE}.
+    #
+    # _@param_ `input` — A string to feed to the child's standard input.
+    #
+    # _@param_ `timeout_s` — Raise {Subprocess::CommunicateTimeout} if communicate does not finish after timeout_s seconds.
+    #
+    # _@return_ — An array of two elements: the data read from the
+    # child's standard output and standard error, respectively.
+    # Returns nil if a block is provided.
+    sig { params(input: T.nilable(String), timeout_s: T.nilable(Numeric)).returns([String, String]) }
+    def communicate(input = nil, timeout_s = nil); end
+
+    # Does exactly what it says on the box.
+    #
+    # _@param_ `signal` — The signal to send to the child process. Accepts all the same arguments as Ruby's built-in {::Process::kill}, for instance a string like "INT" or "SIGINT", or a signal number like 2.
+    #
+    # _@return_ — See {::Process.kill}
+    #
+    # _@see_ `::Process.kill`
+    sig { params(signal: T.any(String, Symbol, Integer)).returns(Integer) }
+    def send_signal(signal); end
+
+    # Sends `SIGTERM` to the process.
+    #
+    # _@return_ — See {send_signal}
+    #
+    # _@see_ `send_signal`
+    sig { returns(Integer) }
+    def terminate; end
+
+    # Return a pair of values (child, mine), which are how the given file
+    # descriptor should appear to the child and to this process, respectively.
+    # "mine" is only non-nil in the case of a pipe (in fact, we just return a
+    # list of length one, since ruby will unpack nils from missing list items).
+    #
+    # _@param_ `fd`
+    #
+    # _@param_ `mode`
+    sig { params(fd: T.nilable(T.any(IO, Integer, String)), mode: String).returns(T::Array[IO]) }
+    def parse_fd(fd, mode); end
+
+    # The pair to parse_fd, returns whether or not the file descriptor was
+    # opened by us (and therefore should be closed by us).
+    #
+    # _@param_ `fd`
+    sig { params(fd: T.nilable(T.any(IO, Integer, String))).returns(T::Boolean) }
+    def our_fd?(fd); end
+
+    # Call IO.select timing out at Time `timeout_at`. If `timeout_at` is nil, never times out.
+    #
+    # _@param_ `read_array`
+    #
+    # _@param_ `write_array`
+    #
+    # _@param_ `err_array`
+    #
+    # _@param_ `timeout_at`
+    sig do
+      params(
+        read_array: T.nilable(T::Array[IO]),
+        write_array: T.nilable(T::Array[IO]),
+        err_array: T.nilable(T::Array[IO]),
+        timeout_at: T.nilable(T.any(Integer, Float))
+      ).returns(T.nilable(T::Array[T::Array[IO]]))
+    end
+    def select_until(read_array, write_array, err_array, timeout_at); end
+
+    sig { void }
+    def self.handle_sigchld; end
+
+    # Wake up everyone. We can't tell who we should wake up without `wait`ing,
+    # and we want to let the process itself do that. In practice, we're not
+    # likely to have that many in-flight subprocesses, so this is probably not a
+    # big deal.
+    sig { void }
+    def self.wakeup_sigchld; end
+
+    # _@param_ `pid`
+    #
+    # _@param_ `fd`
+    sig { params(pid: Integer, fd: IO).void }
+    def self.register_pid(pid, fd); end
+
+    # _@param_ `pid`
+    sig { params(pid: Integer).void }
+    def self.unregister_pid(pid); end
+
+    # _@param_ `pid`
+    sig { params(pid: Integer).void }
+    def self.catching_sigchld(pid); end
+
+    # _@return_ — The `IO` that is connected to this process's `stdin`.
+    sig { returns(IO) }
+    attr_reader :stdin
+
+    # _@return_ — The `IO` that is connected to this process's `stdout`.
+    sig { returns(IO) }
+    attr_reader :stdout
+
+    # _@return_ — The `IO` that is connected to this process's `stderr`.
+    sig { returns(IO) }
+    attr_reader :stderr
+
+    # _@return_ — The command this process was invoked with.
+    sig { returns(T::Array[String]) }
+    attr_reader :command
+
+    # _@return_ — The process ID of the spawned process.
+    sig { returns(Integer) }
+    attr_reader :pid
+
+    # _@return_ — The exit status code of the process. Only
+    # set after the process has exited.
+    sig { returns(::Process::Status) }
+    attr_reader :status
+  end
+end

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: subprocess
 version: !ruby/object:Gem::Version
-  version: 1.1.0
-  prerelease: 
+  version: 1.5.4
 platform: ruby
 authors:
 - Carl Jackson
@@ -10,57 +9,65 @@ authors:
 - Nelson Elhage
 - Andy Brody
 - Andreas Fuchs
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2014-04-30 00:00:00.000000000 Z
+date: 2021-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Control and communicate with spawned processes
@@ -74,33 +81,31 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/subprocess/version.rb
-- lib/subprocess.rb
 - README.md
+- lib/subprocess.rb
+- lib/subprocess/version.rb
+- rbi/subprocess.rbi
 homepage: https://github.com/stripe/subprocess
 licenses:
 - MIT
-post_install_message: 
+metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.23
-signing_key: 
-specification_version: 3
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
 summary: A port of Python's subprocess module to Ruby
 test_files: []
-has_rdoc: