process_executer 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86a47c55d9ddea5ca45bd4126af5e2e09a50348e44d65ef089e6f4eab69eb302
-  data.tar.gz: 06b0a7ea4a9a134b5554b4dd673ecc087cf21d255e57dd18aca164644e4df644
+  metadata.gz: ae4d5881afe09475a15692bf7110746ff4dfd76a70958775351c6fb510a7fb2f
+  data.tar.gz: 683508220b6137f2129bf094b823862ae155a7a5b418aced87dd0056bb0eda7f
 SHA512:
-  metadata.gz: 5625c64aee302c872b097ffd4cf88ddaf3b28ebcfd5d1cfc52dacd53ab9ef4cbb323b7d6b985db3038ce2f86eb2891deb6245d7b047bd219e35d09415fa15fa0
-  data.tar.gz: 970147ff7974931dacaa0701ca32f5abcc540ade99ed8ca2b1b70b73cfa215bb09540931fc182fb67db13cbc920e17e3b55c9d07180fea98ed6bc0571aed6568
+  metadata.gz: 506898e021e1bf3b923d3900fb83005836e729daf064885c0d8172a35690fc9f7865d716197ce60cfb6d6a5153817bde385f6b5b38165296b7f1c213a7a6cfe3
+  data.tar.gz: 3111bfbaf30068de540fb1463a8f862a1d55d6c26f3c47cc90776b2d111a3330601927d4c7e70dcc719ea7c6e60da447c6a2b9b6bddeb89749f44e106a71847e

data/CHANGELOG.md

@@ -1,6 +1,26 @@
+# Changelog
+
+All notable changes to the process_executer gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.3.0 (2022-12-01)
+
+[Full Changelog](https://github.com/main-branch/process_executer/compare/v0.2.0...v0.3.0)
+
+* 6e2cdf1 Completely refactor to a single ProcessExecuter.spawn method (#7)
+* 6da57ec Add CodeClimate badges to README.md (#6)
+* eebd6ae Add front matter and v0.1.0 release to changelog (#5)
+* 78cb9e5 Release v0.2.0
+
 ## v0.2.0 (2022-11-16)
 
 [Full Changelog](https://github.com/main-branch/process_executer/compare/v0.1.0...v0.2.0)
 
 * 8b70ac0 Use the create_github_release gem to make the release PR (#2)
 * 4b2700e Add ProcessExecuter#execute to execute a command and return the result (#1)
+
+## v0.1.0 (2022-10-20)
+
+Initial release of an empty project

data/README.md

@@ -1,6 +1,67 @@
 # The ProcessExecuter Gem
 
-An API for executing commands in a subprocess
+[![Gem Version](https://badge.fury.io/rb/process_executer.svg)](https://badge.fury.io/rb/process_executer)
+[![Build Status](https://github.com/main-branch/process_executer/workflows/Ruby/badge.svg?branch=main)](https://github.com/main-branch/process_executer/actions?query=workflow%3ARuby)
+[![Maintainability](https://api.codeclimate.com/v1/badges/0b5c67e5c2a773009cd0/maintainability)](https://codeclimate.com/github/main-branch/process_executer/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/0b5c67e5c2a773009cd0/test_coverage)](https://codeclimate.com/github/main-branch/process_executer/test_coverage)
+
+## Features
+
+This gem contains the following features:
+
+### ProcessExecuter::MonitoredPipe
+
+`ProcessExecuter::MonitoredPipe` streams data sent through a pipe to one or more writers.
+
+When a new `MonitoredPipe` is created, an pipe is created (via IO.pipe) and
+a thread is created which reads data as it is written written to the pipe.
+
+Data that is read from the pipe is written one or more writers passed to
+`MonitoredPipe#initialize`.
+
+This is useful for streaming process output (stdout and/or stderr) to anything that has a
+`#write` method: a string buffer, a file, or stdout/stderr as seen in the following example:
+
+```ruby
+require 'stringio'
+require 'process_executer'
+
+output_buffer = StringIO.new
+out_pipe = ProcessExecuter::MonitoredPipe.new(output_buffer)
+pid, status = Process.wait2(Process.spawn('echo "Hello World"', out: out_pipe))
+output_buffer.string #=> "Hello World\n"
+```
+
+`MonitoredPipe#initialize` can take more than one writer so that pipe output can be
+streamed (or `tee`d) to multiple writers at the same time:
+
+```ruby
+require 'stringio'
+require 'process_executer'
+
+output_buffer = StringIO.new
+output_file = File.open('process.out', 'w')
+out_pipe = ProcessExecuter::MonitoredPipe.new(output_buffer, output_file)
+pid, status = Process.wait2(Process.spawn('echo "Hello World"', out: out_pipe))
+output_file.close
+output_buffer.string #=> "Hello World\n"
+File.read('process.out') #=> "Hello World\n"
+```
+
+Since the data is streamed, any object that implements `#write` can be used. For insance,
+you can use it to parse process output as a stream which might be useful for long XML
+or JSON output.
+
+### ProcessExecuter.spawn
+
+`ProcessExecuter.spawn` has the same interface as `Process.spawn` but has two
+important behaviorial differences:
+
+1. It blocks until the subprocess finishes
+2. A timeout can be specified using the `:timeout` option
+
+If the command does not terminate before the timeout, the process is killed by
+sending it the SIGKILL signal.
 
 ## Installation
 
@@ -37,27 +98,6 @@ commits and the created tag, and push the `.gem` file to
 Bug reports and pull requests are welcome on our
 [GitHub issue tracker](https://github.com/main-branch/process_executer)
 
-## Feature Checklist
-
-Here is the 1.0 feature checklist:
-
-* [x] Run a command
-* [x] Collect the command's stdout/stderr to a string
-* [x] Passthru the command's stdout/stderr to this process's stdout/stderr
-* [ ] Command execution timeout
-* [ ] Redirect stdout/stderr to a named file
-* [ ] Redirect stdout/stderr to a named file with open mode
-* [ ] Redirect stdout/stderr to a named file with open mode and permissions
-* [ ] Redirect stdout/stderr to an open File object
-* [ ] Merge stdout & stderr
-* [ ] Redirect a file to stdin
-* [ ] Redirect from a butter to stdin
-* [ ] Binary vs. text mode for stdin/stdout/stderr
-* [ ] Environment isolation like Process.spawn
-* [ ] Pass options to Process.spawn (chdir, umask, pgroup, etc.)
-* [ ] Don't allow optionis to Process.spawn that would break the functionality
-    (:in, :out, :err, integer, #fileno, :close_others)
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/process_executer/monitored_pipe.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'io/wait'
+
+module ProcessExecuter
+  # Stream data sent through a pipe to one or more writers
+  #
+  # When a new MonitoredPipe is created, a pipe is created (via IO.pipe) and
+  # a thread is created to read data written to the pipe.
+  #
+  # Data that is read from the pipe is written one or more writers passed to
+  # `#initialize`.
+  #
+  # `#close` must be called to ensure that (1) the pipe is closed, (2) all data is
+  # read from the pipe and written to the writers, and (3) the monitoring thread is
+  # killed.
+  #
+  # @example Collect pipe data into a string
+  #   pipe_data = StringIO.new
+  #   begin
+  #     pipe = MonitoredPipe.new(pipe_data)
+  #     pipe.write("Hello World")
+  #   ensure
+  #     pipe.close
+  #   end
+  #   pipe_data.string #=> "Hello World"
+  #
+  # @example Collect pipe data into a string AND a file
+  #   pipe_data_string = StringIO.new
+  #   pipe_data_file = File.open("pipe_data.txt", "w")
+  #   begin
+  #     pipe = MonitoredPipe.new(pipe_data_string, pipe_data_file)
+  #     pipe.write("Hello World")
+  #   ensure
+  #     pipe.close
+  #   end
+  #   pipe_data_string.string #=> "Hello World"
+  #   File.read("pipe_data.txt") #=> "Hello World"
+  #
+  # @api public
+  #
+  class MonitoredPipe
+    # Create a new monitored pipe
+    #
+    # Creates a IO.pipe and starts a monitoring thread to read data written to the pipe.
+    #
+    # @example
+    #   data_collector = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
+    #
+    # @param writers [Array<#write>] as data is read from the pipe, it is written to these writers
+    # @param chunk_size [Integer] the size of the chunks to read from the pipe
+    #
+    def initialize(*writers, chunk_size: 1000)
+      @pipe_reader, @pipe_writer = IO.pipe
+      @chunk_size = chunk_size
+      @writers = writers
+      @thread = Thread.new { monitor_pipe }
+    end
+
+    # Kill the monitoring thread, read remaining data, and close the pipe
+    #
+    # @example
+    #   require 'stringio'
+    #   data_collector = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
+    #   pipe.write('Hello World')
+    #   pipe.close
+    #   data_collector.string #=> "Hello World"
+    #
+    # @return [void]
+    #
+    def close
+      thread.kill
+      thread.join
+      pipe_writer.close
+      read_pipe_output if pipe_reader.wait_readable(0)
+      pipe_reader.close
+    end
+
+    # Return the write end of the pipe so that data can be written to it
+    #
+    # Data written to this end of the pipe will be read by the monitor thread and
+    # written to the writers passed to `#initialize`.
+    #
+    # This is so we can provide a MonitoredPipe to Process.spawn as a FD
+    #
+    # @example
+    #   require 'stringio'
+    #   data_collector = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
+    #   pipe.to_io.write('Hello World')
+    #   pipe.close
+    #   data_collector.string #=> "Hello World"
+    #
+    # @return [IO] the write end of the pipe
+    #
+    # @api private
+    #
+    def to_io
+      pipe_writer
+    end
+
+    # @!attribute [r] fileno
+    #
+    # The file descriptor for the write end of the pipe
+    #
+    # @example
+    #   require 'stringio'
+    #   data_collector = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
+    #   pipe.fileno == pipe.to_io.fileno #=> true
+    #
+    # @return [Integer] the file descriptor for the write end of the pipe
+    #
+    # @api private
+    #
+    def fileno
+      pipe_writer.fileno
+    end
+
+    # Writes data to the pipe so that it can be read by the monitor thread
+    #
+    # Primarily used for testing.
+    #
+    # @example
+    #   require 'stringio'
+    #   data_collector = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
+    #   pipe.write('Hello World')
+    #   pipe.close
+    #   data_collector.string #=> "Hello World"
+    #
+    # @param data [String] the data to write to the pipe
+    #
+    # @return [Integer] the number of bytes written to the pipe
+    #
+    # @api private
+    #
+    def write(data)
+      pipe_writer.write(data)
+    end
+
+    # @!attribute [r]
+    #
+    # The size of the chunks to read from the pipe
+    #
+    # @example
+    #   require 'stringio'
+    #   data_collector = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
+    #   pipe.chunk_size #=> 1000
+    #
+    # @return [Integer] the size of the chunks to read from the pipe
+    #
+    attr_reader :chunk_size
+
+    # @!attribute [r]
+    #
+    # An array of writers to write data that is read from the pipe
+    #
+    # @example with one writer
+    #   require 'stringio'
+    #   data_collector = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
+    #   pipe.writers #=> [data_collector]
+    #
+    # @example with an array of writers
+    #   require 'stringio'
+    #   data_collector1 = StringIO.new
+    #   data_collector2 = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector1, data_collector2)
+    #   pipe.writers #=> [data_collector1, data_collector2]]
+    #
+    # @return [Array<#write>]
+    #
+    attr_reader :writers
+
+    # @!attribute [r]
+    #
+    # The thread that monitors the pipe
+    #
+    # @example
+    #   require 'stringio'
+    #   data_collector = StringIO.new
+    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
+    #   pipe.thread #=> #<Thread:0x00007f8b1a0b0e00>
+    #
+    # @return [Thread]
+    attr_reader :thread
+
+    # @!attribute [r]
+    #
+    # The read end of the pipe
+    #
+    # @example
+    #   pipe = ProcessExecuter::MonitoredPipe.new($stdout)
+    #   pipe.pipe_reader #=> #<IO:fd 11>
+    #
+    # @return [IO]
+    attr_reader :pipe_reader
+
+    # @!attribute [r]
+    #
+    # The write end of the pipe
+    #
+    # @example
+    #   pipe = ProcessExecuter::MonitoredPipe.new($stdout)
+    #   pipe.pipe_writer #=> #<IO:fd 12>
+    #
+    # @return [IO] the write end of the pipe
+    attr_reader :pipe_writer
+
+    private
+
+    # Reads data from the pipe forever until the monitoring thread is killed
+    # @return [void]
+    # @api private
+    def monitor_pipe
+      loop do
+        read_pipe_output if pipe_reader.wait_readable
+      end
+    end
+
+    # Read a chunk of data from the pipe and write it to the writers
+    # @return [void]
+    # @api private
+    def read_pipe_output
+      new_data = pipe_reader.read_nonblock(chunk_size)
+      # puts "Received new data: #{new_data.inspect} from #{pipe_reader.inspect}"
+      writers.each { |w| w.write(new_data) }
+    rescue EOFError, IO::EAGAINWaitReadable
+      # No output to read at this time
+    end
+  end
+end

data/lib/process_executer/options.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'ostruct'
+
+module ProcessExecuter
+  # Validate ProcessExecuter::Executer#spawn options and return Process.spawn options
+  #
+  # Valid options are those accepted by Process.spawn plus the following additions:
+  #
+  # * `:timeout`:
+  #
+  # @api public
+  #
+  class Options
+    # These options should be passed to `Process.spawn`
+    #
+    # Additionally, any options whose key is an Integer or an IO object will
+    # be passed to `Process.spawn`.
+    #
+    SPAWN_OPTIONS = %i[
+      in out err unsetenv_others pgroup new_pgroup rlimit_resourcename umask
+      close_others chdir
+    ].freeze
+
+    # These options are allowed but should NOT be passed to `Process.spawn`
+    #
+    NON_SPAWN_OPTIONS = %i[
+      timeout
+    ].freeze
+
+    # Any `SPAWN_OPTIONS`` set to this value will not be passed to `Process.spawn`
+    #
+    NOT_SET = :not_set
+
+    # The default values for all options
+    # @return [Hash]
+    DEFAULTS = {
+      in: NOT_SET,
+      out: NOT_SET,
+      err: NOT_SET,
+      unsetenv_others: NOT_SET,
+      pgroup: NOT_SET,
+      new_pgroup: NOT_SET,
+      rlimit_resourcename: NOT_SET,
+      umask: NOT_SET,
+      close_others: NOT_SET,
+      chdir: NOT_SET,
+      timeout: nil
+    }.freeze
+
+    # All options allowed by this class
+    #
+    ALL_OPTIONS = (SPAWN_OPTIONS + NON_SPAWN_OPTIONS).freeze
+
+    # Create accessor functions for all options. Assumes that the options are stored
+    # in a hash named `@options`
+    #
+    ALL_OPTIONS.each do |option|
+      define_method(option) do
+        @options[option]
+      end
+    end
+
+    # Create a new Options object
+    #
+    # @example
+    #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout: 10)
+    #
+    # @param options [Hash] Process.spawn options plus additional options listed below.
+    #
+    #   See [Process.spawn](https://ruby-doc.org/core/Process.html#method-c-spawn)
+    #   for a list of valid.
+    #
+    # @option options [Integer, Float, nil] :timeout
+    #   Number of seconds to wait for the process to terminate. Any number
+    #   may be used, including Floats to specify fractional seconds. A value of 0 or nil
+    #   will allow the process to run indefinitely.
+    #
+    def initialize(**options)
+      assert_no_unknown_options(options)
+      @options = DEFAULTS.merge(options)
+    end
+
+    # Returns the options to be passed to Process.spawn
+    #
+    # @example
+    #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout: 10)
+    #   options.spawn_options # => { out: $stdout, err: $stderr }
+    #
+    # @return [Hash]
+    #
+    def spawn_options
+      {}.tap do |spawn_options|
+        options.each do |option, value|
+          spawn_options[option] = value if include_spawn_option?(option, value)
+        end
+      end
+    end
+
+    private
+
+    # @!attribute [r]
+    #
+    # Options with values
+    #
+    # All options have values. If an option is not given in the initializer, it
+    # will have the value `NOT_SET`.
+    #
+    # @return [Hash<Symbol, Object>]
+    #
+    # @api private
+    #
+    attr_reader :options
+
+    # Determine if the options hash contains any unknown options
+    # @param options [Hash] the hash of options
+    # @return [void]
+    # @raise [ArgumentError] if the options hash contains any unknown options
+    # @api private
+    def assert_no_unknown_options(options)
+      unknown_options = options.keys.reject { |key| valid_option?(key) }
+      raise ArgumentError, "Unknown options: #{unknown_options.join(', ')}" unless unknown_options.empty?
+    end
+
+    # Determine if the given option is a valid option
+    # @param option [Symbol] the option to be tested
+    # @return [Boolean] true if the given option is a valid option
+    # @api private
+    def valid_option?(option)
+      ALL_OPTIONS.include?(option) || option.is_a?(Integer) || option.respond_to?(:fileno)
+    end
+
+    # Determine if the given option should be passed to `Process.spawn`
+    # @param option [Symbol, Integer, IO] the option to be tested
+    # @param value [Object] the value of the option
+    # @return [Boolean] true if the given option should be passed to `Process.spawn`
+    # @api private
+    def include_spawn_option?(option, value)
+      (option.is_a?(Integer) || option.is_a?(IO) || SPAWN_OPTIONS.include?(option)) && value != NOT_SET
+    end
+  end
+end

data/lib/process_executer/process.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  # Spawns a process and knows how to check if the process is terminated
+  #
+  # This class is not currently used in this Gem.
+  #
+  # @api public
+  #
+  class Process
+    # Spawns a new process using Process.spawn
+    #
+    # @example
+    #   command = ['echo', 'hello world']
+    #   options = { chdir: '/tmp' }
+    #   process = ProcessExecuter::Process.new(*command, **options)
+    #   process.pid # => 12345
+    #   process.terminated? # => true
+    #   process.status # => #<Process::Status: pid 12345 exit 0>
+    #
+    # @see https://ruby-doc.org/core/Process.html#method-c-spawn Process.spawn documentation
+    #
+    # @param command [Array] the command to execute
+    # @param spawn_options [Hash] the options to pass to Process.spawn
+    #
+    def initialize(*command, **spawn_options)
+      @pid = ::Process.spawn(*command, **spawn_options)
+    end
+
+    # @!attribute [r]
+    #
+    # The id of the process
+    #
+    # @example
+    #   ProcessExecuter::Process.new('echo', 'hello world').pid # => 12345
+    #
+    # @return [Integer] The id of the process
+    #
+    attr_reader :pid
+
+    # @!attribute [r]
+    #
+    # The exit status of the process or `nil` if the process has not terminated
+    #
+    # @example
+    #   ProcessExecuter::Process.new('echo', 'hello world').status # => #<Process::Status: pid 12345 exit 0>
+    #
+    # @return [::Process::Status, nil]
+    #
+    #   The status is set only when `terminated?` is called and returns `true`.
+    #
+    attr_reader :status
+
+    # Return true if the process has terminated
+    #
+    # If the proces has terminated, `#status` is set to the exit status of the process.
+    #
+    # @example
+    #   process = ProcessExecuter::Process.new('echo', 'hello world')
+    #   sleep 1
+    #   process.terminated? # => true
+    #
+    # @return [Boolean] true if the process has terminated
+    #
+    def terminated?
+      return true if @status
+
+      _pid, @status = ::Process.wait2(pid, ::Process::WNOHANG)
+      !@status.nil?
+    end
+  end
+end

data/lib/process_executer/status.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  # A replacement for Process::Status that can be used to mock the exit status of a process
+  #
+  # This class is not currently used in this Gem.
+  #
+  # Process::Status encapsulates the information on the status of a running or
+  # terminated system process. The built-in variable $? is either nil or a
+  # Process::Status object.
+  #
+  # ```ruby
+  # fork { exit 99 }   #=> 26557
+  # Process.wait       #=> 26557
+  # $?.class           #=> Process::Status
+  # $?.to_i            #=> 25344
+  # $? >> 8            #=> 99
+  # $?.stopped?        #=> false
+  # $?.exited?         #=> true
+  # $?.exitstatus      #=> 99
+  # ```
+  #
+  # Posix systems record information on processes using a 16-bit integer. The
+  # lower bits record the process status (stopped, exited, signaled) and the
+  # upper bits possibly contain additional information (for example the program's
+  # return code in the case of exited processes). Pre Ruby 1.8, these bits were
+  # exposed directly to the Ruby program. Ruby now encapsulates these in a
+  # Process::Status object. To maximize compatibility, however, these objects
+  # retain a bit-oriented interface. In the descriptions that follow, when we
+  # talk about the integer value of stat, we're referring to this 16 bit value.
+  #
+  # @api public
+  #
+  class Status
+    # Create a new Status object
+    #
+    # @example
+    #   status = ProcessExecuter::Status.new(999, 0)
+    #   status.exited? # => true
+    #   status.success? # => true
+    #   status.exitstatus # => 0
+    #
+    def initialize(pid, stat)
+      @pid = pid
+      @stat = stat
+    end
+
+    # @!attribute
+    #
+    # The pid of the process
+    #
+    # @example
+    #   status = ProcessExecuter::Status.new(999, 0)
+    #   status.pid # => 999
+    #
+    # @return [Integer]
+    #
+    # @api public
+    #
+    attr_reader :pid
+
+    # @!attribute
+    #
+    # The status code of the process
+    #
+    # @example
+    #   status = ProcessExecuter::Status.new(999, 123)
+    #   status.stat # => 123
+    #
+    # @return [Integer]
+    #
+    # @api public
+    #
+    attr_reader :stat
+
+    # Logical AND of the bits in stat with `other`
+    #
+    # @example Process ended due to an uncaught signal 11 with a core dump
+    #   status = ProcessExecuter::Status.new(999, 139)
+    #   status & 127 # => 11 => the uncaught signal
+    #   !(status & 128).zero? # => true => indicating a core dump
+    #
+    # @param other [Integer] the value to AND with stat
+    #
+    # @return [Integer] the result of the AND operation
+    #
+    def &(other)
+      stat & other
+    end
+
+    # Compare stat to `other`
+    #
+    # @example Process exited normally with exitstatus 99
+    #   status = ProcessExecuter::Status.new(999, 25_344)
+    #   status == 25_344 # => true
+    #
+    # @param other [Integer] the value to compare stat to
+    #
+    # @return [Boolean] true if stat == other, false otherwise
+    #
+    def ==(other)
+      stat == other
+    end
+
+    # rubocop:disable Naming/BinaryOperatorParameterName
+
+    # Shift the bits in stat right `num` places
+    #
+    # @example Process exited normally with exitstatus 99
+    #   status = ProcessExecuter::Status.new(999, 25_344)
+    #   status >> 8 # => 99
+    #
+    # @param num [Integer] the number of places to shift stat
+    #
+    # @return [Integer] the result of the shift operation
+    #
+    def >>(num)
+      stat >> num
+    end
+
+    # rubocop:enable Naming/BinaryOperatorParameterName
+
+    # Returns true if the process generated a coredump upon termination
+    #
+    # Not available on all platforms.
+    #
+    # @example process exited normally with exitstatus 99
+    #   status = ProcessExecuter::Status.new(999, 25_344)
+    #   status.coredump? # => false
+    #
+    # @example process ended due to an uncaught signal 11 with a core dump
+    #   status = ProcessExecuter::Status.new(999, 139)
+    #   status.coredump? # => true
+    #
+    # @return [Boolean] true if stat generated a coredump when it terminated
+    #
+    def coredump?
+      !(stat & 128).zero?
+    end
+
+    # Returns true if the process exited normally
+    #
+    # This happens when the process uses an exit() call or runs to the end of the program.
+    #
+    # @example process exited normally with exitstatus 0
+    #   status = ProcessExecuter::Status.new(999, 0)
+    #   status.exited? # => true
+    #
+    # @example process exited normally with exitstatus 99
+    #   status = ProcessExecuter::Status.new(999, 25_344)
+    #   status.exited? # => true
+    #
+    # @example process ended due to an uncaught signal 11 with a core dump
+    #   status = ProcessExecuter::Status.new(999, 139)
+    #   status.exited? # => false
+    #
+    # @return [Boolean] true if the process exited normally
+    #
+    def exited?
+      (stat & 127).zero?
+    end
+
+    # Returns the exit status of the process
+    #
+    # Returns nil if the process did not exit normally (when `#exited?` is false).
+    #
+    # @example process exited normally with exitstatus 99
+    #   status = ProcessExecuter::Status.new(999, 25_344)
+    #   status.exitstatus # => 99
+    #
+    # @return [Integer, nil] the exit status of the process
+    #
+    def exitstatus
+      stat >> 8 if exited?
+    end
+
+    # Returns true if the process was successful
+    #
+    # This means that `exited?` is true and `#exitstatus` is 0.
+    #
+    # Returns nil if the process did not exit normally (when `#exited?` is false).
+    #
+    # @example process exited normally with exitstatus 0
+    #   status = ProcessExecuter::Status.new(999, 0)
+    #   status.success? # => true
+    #
+    # @example process exited normally with exitstatus 99
+    #   status = ProcessExecuter::Status.new(999, 25_344)
+    #   status.success? # => false
+    #
+    # @example process ended due to an uncaught signal 11 with a core dump
+    #   status = ProcessExecuter::Status.new(999, 139)
+    #   status.success? # => nil
+    #
+    # @return [Boolean, nil] true if successful, false if unsuccessful, nil if the process did not exit normally
+    #
+    def success?
+      exitstatus.zero? if exited?
+    end
+
+    # Returns true if the process was stopped
+    #
+    # @example with a stopped process with signal 17
+    #   status = ProcessExecuter::Status.new(999, 4_479)
+    #   status.stopped? # => true
+    #
+    # @example process exited normally with exitstatus 99
+    #   status = ProcessExecuter::Status.new(999, 25_344)
+    #   status.stopped? # => false
+    #
+    # @example process ended due to an uncaught signal 11 with a core dump
+    #   status = ProcessExecuter::Status.new(999, 139)
+    #   status.stopped? # => false
+    #
+    # @return [Boolean] true if the process was stopped, false otherwise
+    #
+    def stopped?
+      (stat & 127) == 127
+    end
+
+    # The signal number that casused the process to stop
+    #
+    # Returns nil if the process is not stopped.
+    #
+    # @example with a stopped process with signal 17
+    #   status = ProcessExecuter::Status.new(999, 4_479)
+    #   status.stopsig # => 17
+    #
+    # @example process exited normally with exitstatus 99
+    #   status = ProcessExecuter::Status.new(999, 25_344)
+    #   status.stopsig # => nil
+    #
+    # @return [Integer, nil] the signal number that caused the process to stop or nil
+    #
+    def stopsig
+      stat >> 8 if stopped?
+    end
+
+    # Returns true if stat terminated because of an uncaught signal
+    #
+    # @example process ended due to an uncaught signal 9
+    #   status = ProcessExecuter::Status.new(999, 9)
+    #   status.signaled? # => true
+    #
+    # @example process exited normally with exitstatus 0
+    #   status = ProcessExecuter::Status.new(999, 0)
+    #   status.signaled? # => false
+    #
+    # @return [Boolean] true if stat terminated because of an uncaught signal, false otherwise
+    #
+    def signaled?
+      ![0, 127].include?(stat & 127)
+    end
+
+    # Returns the number of the signal that caused the process to terminate
+    #
+    # Returns nil if the process exited normally or is stopped.
+    #
+    # @example process ended due to an uncaught signal 9
+    #   status = ProcessExecuter::Status.new(999, 9)
+    #   status.termsig # => 9
+    #
+    # @example process exited normally with exitstatus 0
+    #   status = ProcessExecuter::Status.new(999, 0)
+    #   status.termsig # => nil
+    #
+    # @return [Integer, nil] the signal number that caused the process to terminate or nil
+    #
+    def termsig
+      stat & 127 if signaled?
+    end
+
+    # Returns the bits in stat as an Integer
+    #
+    # @example with a stopped process with signal 17
+    #   status = ProcessExecuter::Status.new(999, 4_479)
+    #   status.to_i # => 4_479
+    #
+    # @return [Integer] the bits in stat
+    #
+    def to_i
+      stat
+    end
+
+    # Show the status type, pid, and exit status as a string
+    #
+    # @example with a stopped process with signal 17
+    #   status = ProcessExecuter::Status.new(999, 4_479)
+    #   status.to_s # => "pid 999 stopped SIGSTOP (signal 17)"
+    #
+    # @return [String] the status type, pid, and exit status as a string
+    #
+    def to_s
+      type_to_s + (coredump? ? ' (core dumped)' : '')
+    end
+
+    # Show the status type, pid, and exit status as a string
+    #
+    # @example with a stopped process with signal 17
+    #   status = ProcessExecuter::Status.new(999, 4_479)
+    #   status.inspect # => "#<ProcessExecuter::Status pid 999 stopped SIGSTOP (signal 17)>"
+    #
+    # @return [String] the status type, pid, and exit status as a string
+    #
+    def inspect
+      "#<#{self.class} #{self}>"
+    end
+
+    private
+
+    # The string representation of a status based on how it was terminated
+    # @return [String] the string representation
+    # @api private
+    def type_to_s
+      if signaled?
+        signaled_to_s
+      elsif exited?
+        exited_to_s
+      elsif stopped?
+        stopped_to_s
+      end
+    end
+
+    # The string representation of a signaled process
+    # @return [String] the string representation of a signaled process
+    # @api private
+    def signaled_to_s
+      "pid #{pid} SIG#{Signal.signame(termsig)} (signal #{termsig})"
+    end
+
+    # The string representation of an exited process
+    # @return [String] the string representation of an exited process
+    # @api private
+    def exited_to_s
+      "pid #{pid} exit #{exitstatus}"
+    end
+
+    # The string representation of a stopped process
+    # @return [String] the string representation of a stopped process
+    # @api private
+    def stopped_to_s
+      "pid #{pid} stopped SIG#{Signal.signame(stopsig)} (signal #{stopsig})"
+    end
+  end
+end

data/lib/process_executer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-class ProcessExecuter
-  VERSION = '0.2.0'
+module ProcessExecuter
+  VERSION = '0.3.0'
 end

data/lib/process_executer.rb

@@ -1,225 +1,68 @@
 # frozen_string_literal: true
 
-# rubocop:disable Style/SingleLineMethods
+require 'process_executer/monitored_pipe'
+require 'process_executer/options'
+require 'process_executer/process'
+require 'process_executer/status'
 
-require 'process_executer/result'
-# require 'nio'
+require 'timeout'
 
-# Execute a process and capture the output to a string, a file, and/or
-# pass the output through to this process's stdout/stderr.
+# Execute a command in a subprocess and optionally capture its output
 #
 # @api public
 #
-class ProcessExecuter
-  # stdout collected from the command
+module ProcessExecuter
+  # Execute the specified command and return the exit status
   #
-  # @example
-  #   command = ProcessExecuter.new
-  #   command.execute('echo hello')
-  #   command.out # => "hello\n"
-  #
-  # @return [String, nil] nil if collect_out? is false
-  #
-  attr_reader :out
-
-  # stderr collected from the command
-  #
-  # @example
-  #   command = ProcessExecuter.new
-  #   command.execute('echo hello 1>&2')
-  #   command.err # => "hello\n"
-  #
-  # @return [String, nil] nil if collect_err? is false
-  #
-  attr_reader :err
-
-  # The status of the command process
-  #
-  # Will be `nil` if the command has not completed execution.
-  #
-  # @example
-  #   command = ProcessExecuter.new
-  #   command.execute('echo hello')
-  #   command.status # => #<Process::Status: pid 86235 exit 0>
-  #
-  # @return [Process::Status, nil]
-  #
-  attr_reader :status
-
-  # Show the command's stdout on this process's stdout
-  #
-  # @example
-  #   command = ProcessExecuter.new(passthru_out: true)
-  #   command.passthru_out? # => true
-  #
-  # @return [Boolean]
-  #
-  def passthru_out?; !!@passthru_out; end
-
-  # Show the command's stderr on this process's stderr
-  #
-  # @example
-  #   command = ProcessExecuter.new(passthru_err: true)
-  #   command.passthru_err? # => true
-  #
-  # @return [Boolean]
-  #
-  def passthru_err?; !!@passthru_err; end
-
-  # Collect the command's stdout the :out string (default is true)
+  # This method blocks until the command has terminated or the timeout has been reached.
   #
   # @example
-  #   command = ProcessExecuter.new(collect_out: false)
-  #   command.collect_out? # => false
-  #
-  # @return [Boolean]
-  #
-  def collect_out?; !!@collect_out; end
-
-  # Collect the command's stderr the :err string (default is true)
+  #   status = ProcessExecuter.spawn('echo hello')
+  #   status.exited? # => true
+  #   status.success? # => true
+  #   stdout.string # => "hello\n"
   #
-  # @example
-  #   command = ProcessExecuter.new(collect_err: false)
-  #   command.collect_err? # => false
+  # @example with a timeout
+  #   status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
+  #   status.exited? # => false
+  #   status.success? # => nil
+  #   status.signaled? # => true
+  #   status.termsig # => 9
   #
-  # @return [Boolean]
+  # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-spawn Kernel.spawn
+  #   documentation for valid command and options
   #
-  def collect_err?; !!@collect_err; end
-
-  # Create a new ProcessExecuter
+  # @see ProcessExecuter::Options#initialize See ProcessExecuter::Options#initialize
+  #   for additional options that may be specified
   #
-  # @example
-  #   command = ProcessExecuter.new(passthru_out: false, passthru_err: false)
+  # @param command [Array<String>] the command to execute
+  # @param options_hash [Hash] the options to use for this execution context
   #
-  # @param passthru_out [Boolean] show the command's stdout on this process's stdout
-  # @param passthru_err [Boolean] show the command's stderr on this process's stderr
-  # @param collect_out [Boolean] collect the command's stdout the :out string
-  # @param collect_err [Boolean] collect the command's stderr the :err string
+  # @return [ProcessExecuter::ExecutionContext] the execution context that can run commands
   #
-  def initialize(passthru_out: false, passthru_err: false, collect_out: true, collect_err: true)
-    @passthru_out = passthru_out
-    @passthru_err = passthru_err
-    @collect_out = collect_out
-    @collect_err = collect_err
+  def self.spawn(*command, **options_hash)
+    options = ProcessExecuter::Options.new(**options_hash)
+    pid = ::Process.spawn(*command, **options.spawn_options)
+    wait_for_process(pid, options)
   end
 
-  # rubocop:disable Metrics/AbcSize
-  # rubocop:disable Metrics/MethodLength
-
-  # Execute the given command in a subprocess
+  # Wait for process to terminate
   #
-  # See Process.spawn for acceptable values for command and options.
+  # If a timeout is speecified in options, kill the process after options.timeout seconds.
   #
-  # Do no specify the following options: :in, :out, :err, integer, #fileno, :close_others.
+  # @param pid [Integer] the process id
+  # @param options [ProcessExecuter::Options] the options used
   #
-  # @example Execute a command as a single string
-  #   result = ProcessExecuter.new.execute('echo hello')
+  # @return [ProcessExecuter::Status] the status of the process
   #
-  # @example Execute a command as with each argument as a separate string
-  #  result = ProcessExecuter.new.execute('echo', 'hello')
-  #
-  # @example Execute a command in a specific directory
-  #  result = ProcessExecuter.new.execute('pwd', chdir: '/tmp')
-  #  result.out # => "/tmp\n"
-  #
-  # @example Execute a command with specific environment variables
-  #  result = ProcessExecuter.new.execute({ 'FOO' => 'bar' }, 'echo $FOO' )
-  #  result.out # => "bar\n"
-  #
-  # @param command [String, Array<String>] the command to pass to Process.spawn
-  # @param options [Hash] options to pass to Process.spawn
-  #
-  # @return [ProcessExecuter::Result] the result of the command execution
-  #
-  def execute(*command, **options)
-    @status = nil
-    @out = (collect_out? ? '' : nil)
-    @err = (collect_err? ? '' : nil)
-
-    out_reader, out_writer = IO.pipe
-    err_reader, err_writer = IO.pipe
-
-    options[:out] = out_writer
-    options[:err] = err_writer
-
-    pid = Process.spawn(*command, options)
-
-    loop do
-      read_command_output(out_reader, err_reader)
-
-      _pid, @status = Process.wait2(pid, Process::WNOHANG)
-      break if @status
-
-      # puts "finished_pid: #{finished_pid}"
-      # puts "status: #{status}"
-
-      # puts 'starting select'
-      # readers, writers, exceptions = IO.select([stdout_reader, stderr_reader], nil, nil, 0.1)
-      IO.select([out_reader, err_reader], nil, nil, 0.05)
-
-      # puts "readers: #{readers}"
-      # puts "writers: #{writers}"
-      # puts "exceptions: #{exceptions}"
-
-      # break unless readers || writers || exceptions
-
-      _pid, @status = Process.wait2(pid, Process::WNOHANG)
-      break if @status
-
-      # puts "finished_pid: #{finished_pid}"
-      # puts "status: #{status}"
-    end
-
-    out_writer.close
-    err_writer.close
-
-    # Read whatever is left over after the process terminates
-    read_command_output(out_reader, err_reader)
-    ProcessExecuter::Result.new(@status, @out, @err)
-  end
-
-  # rubocop:enable Metrics/AbcSize
-  # rubocop:enable Metrics/MethodLength
-
-  private
-
-  # Read output from the given readers
-  # @return [void]
   # @api private
-  def read_command_output(out_reader, err_reader)
-    loop do
-      # Keep reading until there is nothing left to read
-      break unless read_out(out_reader) || read_err(err_reader)
+  #
+  private_class_method def self.wait_for_process(pid, options)
+    Timeout.timeout(options.timeout) do
+      ::Process.wait2(pid).last
     end
-  end
-
-  # Read stdout from the given reader
-  # @return [void]
-  # @api private
-  def read_out(reader)
-    new_data = reader.read_nonblock(1024)
-    # puts "new_stdout: '#{new_data}'"
-    @out += new_data if new_data && collect_out?
-    puts new_data if new_data && passthru_out?
-    true
-  rescue EOFError, IO::EAGAINWaitReadable
-    # Nothing to read at this time
-    false
-  end
-
-  # Read stderr from the given reader
-  # @return [void]
-  # @api private
-  def read_err(reader)
-    new_data = reader.read_nonblock(1024)
-    # puts "new_stderr: '#{new_data}'"
-    @err += new_data if new_data && collect_err?
-    warn new_data if new_data && passthru_err?
-    true
-  rescue EOFError, IO::EAGAINWaitReadable
-    # Nothing to read at this time
-    false
+  rescue Timeout::Error
+    ::Process.kill('KILL', pid)
+    ::Process.wait2(pid).last
   end
 end
-
-# rubocop:enable Style/SingleLineMethods

data/process_executer.gemspec

@@ -41,6 +41,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec', '~> 3.10'
   spec.add_development_dependency 'rubocop', '~> 1.36'
   spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'simplecov-lcov', '~> 0.8'
   spec.add_development_dependency 'solargraph', '~> 0.47'
   spec.add_development_dependency 'yard', '~> 0.9'
   spec.add_development_dependency 'yardstick', '~> 0.9'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-11-16 00:00:00.000000000 Z
+date: 2022-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: solargraph
   requirement: !ruby/object:Gem::Requirement
@@ -181,7 +195,10 @@ files:
 - README.md
 - Rakefile
 - lib/process_executer.rb
-- lib/process_executer/result.rb
+- lib/process_executer/monitored_pipe.rb
+- lib/process_executer/options.rb
+- lib/process_executer/process.rb
+- lib/process_executer/status.rb
 - lib/process_executer/version.rb
 - process_executer.gemspec
 homepage: https://github.com/main_branch/process_executer

data/lib/process_executer/result.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-class ProcessExecuter
-  # The result of executing a command
-  #
-  # @api public
-  #
-  class Result
-    # The status of the command process
-    #
-    # @example
-    #   status # => #<Process::Status: pid 86235 exit 0>
-    #   out = 'hello'
-    #   err = 'ERROR'
-    #   command = ProcessExecuter.new(status, out, err)
-    #   command.status # => #<Process::Status: pid 86235 exit 0>
-    #
-    # @return [Process::Status]
-    #
-    attr_reader :status
-
-    # The command's stdout (if collected)
-    #
-    # @example
-    #   status # => #<Process::Status: pid 86235 exit 0>
-    #   out = 'hello'
-    #   err = 'ERROR'
-    #   command = ProcessExecuter.new(status, out, err)
-    #   command.out # => "hello\n"
-    #
-    # @return [String, nil]
-    #
-    attr_reader :out
-
-    # The command's stderr (if collected)
-    #
-    # @example
-    #   status # => #<Process::Status: pid 86235 exit 0>
-    #   out = 'hello'
-    #   err = 'ERROR'
-    #   command = ProcessExecuter.new(status, out, err)
-    #   command.out # => "ERROR\n"
-    #
-    # @return [String, nil]
-    #
-    attr_reader :err
-
-    # Create a new Result object
-    #
-    # @example
-    #   status # => #<Process::Status: pid 86235 exit 0>
-    #   out = 'hello'
-    #   err = 'ERROR'
-    #   command = ProcessExecuter.new(status, out, err)
-    #
-    # @param status [Process::Status] the status of the command process
-    # @param out [String, nil] the command's stdout (if collected)
-    # @param err [String, nil] the command's stderr (if collected)
-    #
-    # @return [ProcessExecuter::Result] the result object
-    #
-    def initialize(status, out, err)
-      @status = status
-      @out = out
-      @err = err
-    end
-  end
-end