process_executer 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc6b432be7a421bc53561149ce4718a41fd7ff61b1b2213498000891c388a0c9
-  data.tar.gz: ce582e04a3500b0b6c0e31af16d2d735e87f9c99c5d82279c591c9e5abc0a619
+  metadata.gz: c6d2904b0fd36166eb05a23f8d208b27de0c19bc10284e71e63a1e7055034a7b
+  data.tar.gz: 5ed998bd38182774d63265bd6729c219918acf41755215a172c87b85e4873ebe
 SHA512:
-  metadata.gz: 312c65d62033f2e3a13ed5094de32940b9923d775d45f3d90dc6cbe4f0a8d0dcf3e5e772e6add2999c97e2b2980b39d4fa3d4f7ddf0172e9877d7e94a1770d94
-  data.tar.gz: 267da77563194721787fee28ff41cdf19159f083f5a0cb04d6d912e0271f2e2062b50da8d1655b36bea2ebb5327f3f3d618aa90453ad60ba61d72e4c779afe84
+  metadata.gz: 7aec2cdf98b06acccccfa449e57efbc3d6ea4b7bb9ee833a5f81ee77faa02490c55d5c3cea7c1235295d765eaf3b957b2577e3cf8fae0818d4e60e097218bcc3
+  data.tar.gz: a0a95d10b07111be5ca3bc094cfa4255629f43b723fb7ae44ead94615c11cd97af370da9a219e481c1d55eb55fd20f7f3a24e213a96834d91b3f18527a6af8ab

data/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.5.0 (2022-12-12)
+
+[Full Changelog](https://github.com/main-branch/process_executer/compare/v0.4.0...v0.5.0)
+
+* c6d8de9 Workaround a problem with SimpleCov / JRuby
+* c480b5f Increase time to wait for results from a writer throwing an exception
+* 1934563 Handle exceptions from writers within MonitoredPipe
+* e948ada Increase default chunk_size to 100_000 bytes
+* 5eb2c24 Update documentation for ProcessExecuter#spawn
+* a3a4217 Release v0.4.0
+
 ## v0.4.0 (2022-12-06)
 
 [Full Changelog](https://github.com/main-branch/process_executer/compare/v0.3.0...v0.4.0)

data/lib/process_executer/monitored_pipe.rb

@@ -12,6 +12,9 @@ module ProcessExecuter
   # Data that is read from that pipe is written one or more writers passed to
   # `#initialize`.
   #
+  # If any of the writers raise an exception, the monitoring thread will exit, the
+  # pipe will be closed, and the exception will be saved in `#exception`.
+  #
   # `#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.
@@ -52,12 +55,16 @@ module ProcessExecuter
     # @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)
+    def initialize(*writers, chunk_size: 100_000)
       @writers = writers
       @chunk_size = chunk_size
       @pipe_reader, @pipe_writer = IO.pipe
       @state = :open
-      @thread = Thread.new { monitor }
+      @thread = Thread.new do
+        Thread.current.report_on_exception = false
+        Thread.current.abort_on_exception = false
+        monitor
+      end
     end
 
     # Set the state to `:closing` and wait for the state to be set to `:closed`
@@ -76,6 +83,8 @@ module ProcessExecuter
     # @return [void]
     #
     def close
+      return unless state == :open
+
       @state = :closing
       sleep 0.01 until state == :closed
     end
@@ -233,6 +242,19 @@ module ProcessExecuter
     #
     attr_reader :state
 
+    # @!attribute [r]
+    #
+    # The exception raised by a writer
+    #
+    # If an exception is raised by a writer, it is stored here. Otherwise, it is `nil`.
+    #
+    # @example
+    #   pipe.exception #=> nil
+    #
+    # @return [Exception, nil] the exception raised by a writer or `nil` if no exception was raised
+    #
+    attr_reader :exception
+
     private
 
     # Read data from the pipe until `#state` is changed to `:closing`
@@ -257,10 +279,17 @@ module ProcessExecuter
     # @api private
     def monitor_pipe
       new_data = pipe_reader.read_nonblock(chunk_size)
+      # SimpleCov under JRuby reports the begin statement as not covered, but it is
+      # :nocov:
+      begin
+        # :nocov:
+        writers.each { |w| w.write(new_data) }
+      rescue StandardError => e
+        @exception = e
+        @state = :closing
+      end
     rescue IO::WaitReadable
       pipe_reader.wait_readable(0.01)
-    else
-      writers.each { |w| w.write(new_data) }
     end
 
     # Read any remaining data from the pipe and close it
@@ -271,7 +300,8 @@ module ProcessExecuter
       # Close the write end of the pipe so no more data can be written to it
       pipe_writer.close
       # Read remaining data from pipe_reader (if any)
-      if pipe_reader.wait_readable(0.01)
+      # If an exception was already raised by the last call to #write, then don't try to read remaining data
+      if exception.nil? && pipe_reader.wait_readable(0.01)
         new_data = pipe_reader.read(chunk_size)
         writers.each { |w| w.write(new_data) }
       end

data/lib/process_executer/version.rb

@@ -2,5 +2,5 @@
 
 module ProcessExecuter
   # The current Gem version
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/process_executer.rb

@@ -10,15 +10,17 @@ require 'timeout'
 # @api public
 #
 module ProcessExecuter
-  # Execute the specified command and return the exit status
+  # Execute the specified command as a subprocess and return the exit status
   #
-  # This method blocks until the command has terminated or the timeout has been reached.
+  # This method blocks until the command has terminated.
+  #
+  # The command will be send the SIGKILL signal if it does not terminate within
+  # the specified timeout.
   #
   # @example
   #   status = ProcessExecuter.spawn('echo hello')
   #   status.exited? # => true
   #   status.success? # => true
-  #   stdout.string # => "hello\n"
   #
   # @example with a timeout
   #   status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
@@ -27,6 +29,11 @@ module ProcessExecuter
   #   status.signaled? # => true
   #   status.termsig # => 9
   #
+  # @example capturing stdout to a string
+  #   stdout = StringIO.new
+  #   status = ProcessExecuter.spawn('echo hello', out: stdout)
+  #   stdout.string # => "hello"
+  #
   # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-spawn Kernel.spawn
   #   documentation for valid command and options
   #
@@ -34,13 +41,13 @@ module ProcessExecuter
   #   for additional options that may be specified
   #
   # @param command [Array<String>] the command to execute
-  # @param options_hash [Hash] the options to use for this execution context
+  # @param options_hash [Hash] the options to use when exectuting the command
   #
-  # @return [ProcessExecuter::ExecutionContext] the execution context that can run commands
+  # @return [Process::Status] the exit status of the proceess
   #
   def self.spawn(*command, **options_hash)
     options = ProcessExecuter::Options.new(**options_hash)
-    pid = ::Process.spawn(*command, **options.spawn_options)
+    pid = Process.spawn(*command, **options.spawn_options)
     wait_for_process(pid, options)
   end
 
@@ -51,16 +58,16 @@ module ProcessExecuter
   # @param pid [Integer] the process id
   # @param options [ProcessExecuter::Options] the options used
   #
-  # @return [ProcessExecuter::Status] the status of the process
+  # @return [Process::Status] the status of the process
   #
   # @api private
   #
   private_class_method def self.wait_for_process(pid, options)
     Timeout.timeout(options.timeout) do
-      ::Process.wait2(pid).last
+      Process.wait2(pid).last
     end
   rescue Timeout::Error
-    ::Process.kill('KILL', pid)
-    ::Process.wait2(pid).last
+    Process.kill('KILL', pid)
+    Process.wait2(pid).last
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-07 00:00:00.000000000 Z
+date: 2022-12-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump