subprocess 1.3.0 → 1.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 82c898802f4160693d7836102254e37c303db198
-  data.tar.gz: 71481f1fe51f83f84be323b801674c6ae34c8723
+SHA256:
+  metadata.gz: ca7ff75142ac9cdc919053f61071f8ff54d21193754239da85b810d0dce7886d
+  data.tar.gz: ae5ec4dedac5fd3042e6006ae798bf286c5705b6aca0da37c398fbd52b16d100
 SHA512:
-  metadata.gz: f3b32e75da714a7eb24ab94fa5486ed190c128b5e1e92fa8545a9797c93ff74cdef92f45a8d3e54b8d6fd653284d85d5640f6c89b926d23f9cfdd01786bbbdf3
-  data.tar.gz: d7d449f41f1d7c2a2201af471916bdac29696cea27058ada2454d91de7ac6543cb56715ae56393dc61b9e9c2c1a31c1fce01b7b76934d1f929909e23307324d1
+  metadata.gz: d0e375e45a5ed1089690a90abe9bf3fcc83754a4bd490047465ff0b83bd82966a5cb73fcd6738cb215c6351784582b90a341ba7ad7315738ef426f532215ed9b
+  data.tar.gz: 87b16802e5534b86c4f2d0ab7b7f5bd0cd885b9375af520341a936c017e5c23a8a33a76bcd7a50566cb9a2631e77fc8c9797779e78e03c0e75afe916d680efb1

data/README.md

@@ -1,14 +1,8 @@
-# Subprocess [![Build Status](https://travis-ci.org/stripe/subprocess.svg?branch=master)](https://travis-ci.org/stripe/subprocess)
+# Subprocess ![Ruby](https://github.com/stripe/subprocess/workflows/Ruby/badge.svg) [![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
 ------------
@@ -21,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'
@@ -71,3 +55,46 @@ 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
+
+Maintenance
+-----------
+
+Steps to release a new version:
+
+```bash
+# Work directly on master
+git checkout master
+
+# -- edit version in lib/subprocess/version.rb --
+
+# Update RBI files
+bundle exec rake sord
+
+# Subsequent commands reference the version
+VERSION=1.5.5
+git commit -am "Bump version to $VERSION"
+git tag "v$VERSION"
+git push origin master --tags
+bundle exec rake publish
+```
+
+If you get errors, ask someone to add you to `bindings/rubygems-api-key` in
+Vault or ask someone who already has permissions. See <http://go/password-vault>
+
+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,14 +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)
-        else
-          # ruby 1.9 way
-          sig_name = Signal.list.key(sig_num)
-        end
+        sig_name = Signal.signame(sig_num)
 
         if sig_name
           parts << "(maybe SIG#{sig_name})"
@@ -137,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}.
     #
@@ -168,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, nil] 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
@@ -214,12 +250,12 @@ 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}.
+    #   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`.
@@ -230,7 +266,7 @@ 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
@@ -250,8 +286,6 @@ module Subprocess
 
       @pid = fork do
         begin
-          FileUtils.cd(opts[:cwd]) if opts[:cwd]
-
           ::STDIN.reopen(@child_stdin) if @child_stdin
           ::STDOUT.reopen(@child_stdout) if @child_stdout
           if opts[:stderr] == STDOUT
@@ -263,24 +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]
+          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]
             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
 
-          # 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)
+          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
 
         rescue Exception => e
           # Dump all errors up to the parent through the control socket
@@ -343,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
@@ -354,40 +408,51 @@ 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?
+
+      # NB: Always force encoding to binary so we handle unicode or binary input
+      # correctly across multiple write_nonblock calls, since we manually slice
+      # the input depending on how many bytes were written
+      input = input.dup.force_encoding('BINARY') 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)
@@ -401,6 +466,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!"
@@ -408,10 +480,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?
@@ -420,29 +506,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
@@ -452,6 +550,10 @@ module Subprocess
     # 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 [IO, Integer, String, nil] fd
+    # @param [String] mode
+    # @return [Array<IO>]
     def parse_fd(fd, mode)
       fds = case fd
       when PIPE
@@ -473,6 +575,9 @@ module Subprocess
 
     # 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
@@ -482,32 +587,92 @@ module Subprocess
       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
@@ -517,11 +682,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.3.0'
+  VERSION = '1.5.5'
 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.5', 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(T.nilable(::Process::Status)) }
+    attr_reader :status
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: subprocess
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.5
 platform: ruby
 authors:
 - Carl Jackson
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-09 00:00:00.000000000 Z
+date: 2021-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -56,6 +56,20 @@ dependencies:
     - - ">="
       - !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
 email:
 - carl@stripe.com
@@ -70,6 +84,7 @@ files:
 - README.md
 - lib/subprocess.rb
 - lib/subprocess/version.rb
+- rbi/subprocess.rbi
 homepage: https://github.com/stripe/subprocess
 licenses:
 - MIT
@@ -89,10 +104,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: A port of Python's subprocess module to Ruby
 test_files: []
-has_rdoc: