process_executer 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec0548ff8356b9466db5fe9c9992e134010c9842561e1b0c0b95a5418fb2c2d2
-  data.tar.gz: 7b9ead3538f7117b453a5353ad0a1ed352b7c60fa86fbacaa12081ff32b411cb
+  metadata.gz: f568a98075e32879207b26949346e4181eed2d2432c9665e84ddb015d5ded96c
+  data.tar.gz: bcc6f74e77155a251d4ad561495f6edb1b6cf95bccc23b7de7322a0897d4a0af
 SHA512:
-  metadata.gz: a35f9cd143bf7236efbb107a8de130784c195bedb83e95262cc26ae7e2b7e586b7230bdf1ad680c508a5dd8b2c3398c89290ad01a1e5914e165179c298bf5b11
-  data.tar.gz: 5dabb78fd2151f587078b3a139974eb390e23e86be961ce93a7d4f65dd161007e8a175b36b208d13939d38cd5dab41f0a446e7d5213aee34c7f07273c4804f49
+  metadata.gz: 0fc886fade1e486d6acb6c32864a469a6d77700c596dd15a47c4e59e440bfda06b3a1ca506fc4a9be8f7d3bea831525329e735d9cb30d5c01d48395571f9164c
+  data.tar.gz: cab6c4b4d5d1761ac46df3aff8c02c44fed93d071bc6c74fdba802c04175321520c92556c8a43fe79bf3f56d9fb80b82e1b7b60ff50c1bdea8fdcf94bb2e22fd

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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).
 
+## v1.1.0 (2024-02-02)
+
+[Full Changelog](https://github.com/main-branch/process_executer/compare/v1.0.2..v1.1.0)
+
+Changes since v1.0.2:
+
+* a473281 ProcessExecuter.spawn should indicate if the subprocess timed out or not (#43)
+
+## v1.0.2 (2024-02-01)
+
+[Full Changelog](https://github.com/main-branch/process_executer/compare/v1.0.1..v1.0.2)
+
+Changes since v1.0.1:
+
+* 76ffb91 An invalid timeout value should raise an ArgumentError (#41)
+* b748819 Release v1.0.1 (#40)
+
+## v1.0.1 (2024-01-04)
+
+[Full Changelog](https://github.com/main-branch/process_executer/compare/v1.0.0..v1.0.1)
+
+Changes since v1.0.0:
+
+* f434aa1 Add an experimental build for jruby-head on windows (#15)
+* 97dbcf5 Make updates resulting from doc review (#38)
+* 93eab18 Release v1.0.0 (#37)
+
 ## v1.0.0 (2023-12-31)
 
 [Full Changelog](https://github.com/main-branch/process_executer/compare/v0.7.0..v1.0.0)

data/README.md

@@ -77,7 +77,15 @@ important behaviorial differences:
 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.
+sending it the SIGKILL signal. The returned status object's `timeout?` attribute will
+return `true`. For example:
+
+```ruby
+status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
+status.signaled? #=> true
+status.termsig #=> 9
+status.timeout? #=> true
+```
 
 ## Installation
 

data/lib/process_executer/options.rb

@@ -2,6 +2,7 @@
 
 require 'forwardable'
 require 'ostruct'
+require 'pp'
 
 module ProcessExecuter
   # Validate ProcessExecuter::Executer#spawn options and return Process.spawn options
@@ -27,13 +28,14 @@ module ProcessExecuter
       close_others chdir
     ].freeze
 
-    # These options are allowed but should NOT be passed to `Process.spawn`
+    # These options are allowed by `ProcessExecuter.spawn` 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`
+    # Any `SPAWN_OPTIONS` set to `NOT_SET` will not be passed to `Process.spawn`
     #
     NOT_SET = :not_set
 
@@ -76,7 +78,7 @@ module ProcessExecuter
     # @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.
+    #   for a list of valid options that can be passed to `Process.spawn`.
     #
     # @option options [Integer, Float, nil] :timeout
     #   Number of seconds to wait for the process to terminate. Any number
@@ -86,6 +88,7 @@ module ProcessExecuter
     def initialize(**options)
       assert_no_unknown_options(options)
       @options = DEFAULTS.merge(options)
+      assert_timeout_is_valid
     end
 
     # Returns the options to be passed to Process.spawn
@@ -129,6 +132,24 @@ module ProcessExecuter
       raise ArgumentError, "Unknown options: #{unknown_options.join(', ')}" unless unknown_options.empty?
     end
 
+    # Raise an error if timeout is not a real non-negative number
+    # @return [void]
+    # @raise [ArgumentError] if timeout is not a real non-negative number
+    # @api private
+    def assert_timeout_is_valid
+      return if @options[:timeout].nil?
+      return if @options[:timeout].is_a?(Numeric) && @options[:timeout].real? && !@options[:timeout].negative?
+
+      raise ArgumentError, invalid_timeout_message
+    end
+
+    # The message to be used when raising an error for an invalid timeout
+    # @return [String]
+    # @api private
+    def invalid_timeout_message
+      "timeout must be nil or a real non-negative number but was #{options[:timeout].pretty_inspect}"
+    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

data/lib/process_executer/status.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module ProcessExecuter
+  # A simple delegator for Process::Status that adds a `timeout?` attribute
+  #
+  # @api public
+  #
+  class Status < SimpleDelegator
+    extend Forwardable
+
+    # Create a new Status object from a Process::Status and timeout flag
+    #
+    # @param status [Process::Status] the status to delegate to
+    # @param timeout [Boolean] true if the process timed out
+    #
+    # @example
+    #   status = Process.wait2(pid).last
+    #   timeout = false
+    #   ProcessExecuter::Status.new(status, timeout)
+    #
+    # @api public
+    #
+    def initialize(status, timeout)
+      super(status)
+      @timeout = timeout
+    end
+
+    # @!attribute [r] timeout?
+    #
+    # True if the process timed out and was sent the SIGKILL signal
+    #
+    # @example
+    #   status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
+    #   status.timeout? # => true
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    #
+    def timeout? = @timeout
+  end
+end

data/lib/process_executer/version.rb

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

data/lib/process_executer.rb

@@ -2,6 +2,7 @@
 
 require 'process_executer/monitored_pipe'
 require 'process_executer/options'
+require 'process_executer/status'
 
 require 'timeout'
 
@@ -12,7 +13,8 @@ require 'timeout'
 module ProcessExecuter
   # Execute the specified command as a subprocess and return the exit status
   #
-  # This method blocks until the command has terminated.
+  # This is a convenience method that calls Process.spawn and blocks until the
+  # command has terminated.
   #
   # The command will be send the SIGKILL signal if it does not terminate within
   # the specified timeout.
@@ -38,7 +40,7 @@ module ProcessExecuter
   #   documentation for valid command and options
   #
   # @see ProcessExecuter::Options#initialize See ProcessExecuter::Options#initialize
-  #   for additional options that may be specified
+  #   for options that may be specified
   #
   # @param command [Array<String>] the command to execute
   # @param options_hash [Hash] the options to use when exectuting the command
@@ -58,16 +60,16 @@ module ProcessExecuter
   # @param pid [Integer] the process id
   # @param options [ProcessExecuter::Options] the options used
   #
-  # @return [Process::Status] the status of the process
+  # @return [ProcessExecuter::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
+      ProcessExecuter::Status.new(Process.wait2(pid).last, false)
     end
   rescue Timeout::Error
     Process.kill('KILL', pid)
-    Process.wait2(pid).last
+    ProcessExecuter::Status.new(Process.wait2(pid).last, true)
   end
 end

data/process_executer.gemspec

@@ -18,7 +18,8 @@ Gem::Specification.new do |spec|
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/main-branch/process_executer'
-  spec.metadata['changelog_uri'] = 'https://rubydoc.info/gems/process_executer/file/CHANGELOG.md'
+  spec.metadata['changelog_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}/file/CHANGELOG.md"
+  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-31 00:00:00.000000000 Z
+date: 2024-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -190,6 +190,7 @@ files:
 - lib/process_executer.rb
 - lib/process_executer/monitored_pipe.rb
 - lib/process_executer/options.rb
+- lib/process_executer/status.rb
 - lib/process_executer/version.rb
 - process_executer.gemspec
 homepage: https://github.com/main-branch/process_executer
@@ -199,7 +200,8 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/main-branch/process_executer
   source_code_uri: https://github.com/main-branch/process_executer
-  changelog_uri: https://rubydoc.info/gems/process_executer/file/CHANGELOG.md
+  changelog_uri: https://rubydoc.info/gems/process_executer/1.1.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/process_executer/1.1.0
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []