sproc 0.3.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8938c9977d79ffd99b2526dc698d66f33c0afc225121307a7cbf79fe9284acdb
-  data.tar.gz: 0fcd34ab808b76a121a581443b0bf9c075e8bf92633a112c406b11b11691b9ab
+  metadata.gz: d2ccda7be2976e3c6daaa74c8a37c858fdc76f5d929e1cf87b77cc7411d9f72d
+  data.tar.gz: ae73fcb466456779be5e91afc1bbe8e67b368bed7f3c834a0d523acaacfdd9a9
 SHA512:
-  metadata.gz: e4da5cce84127eb2b3fda62ba9cb893b588ad1e68b173ad8ef558d8c7f4945c089c74dea20e7be62e7e685bd7efbcf91a6d0616bcc413a7fb4663731151c25da
-  data.tar.gz: 7abf027ed86e29fbc531698feec84c318fda64d3138fa3e22bce81c1f2ef7a79b73aa255274de5f0265453c8df59964a616b912cb41cb55b8e692cd36b0d1fae
+  metadata.gz: abc0511633bf642dfaffd0a35f00f9d257bc38f316010418932b910bfeebbcb7d7c7f479aa70fed8aa31fe6be24eacc19f69a0108a17d766910c7145da3e194a
+  data.tar.gz: 6d00c01bf0791f2919b37449cf76ee95a71dba9aa95713e0c0955dd37bcb4c9a41b7881e7a4e7058d8800c64963ea78bb804550e6bd66cf0e4e1fada40daf82f

data/lib/sproc.rb

@@ -2,6 +2,7 @@
 
 require_relative "sproc/version"
 require_relative "sproc/core"
+require_relative "sproc/osinfo"
 
 module SProc
   class Error < StandardError; end

data/lib/sproc/core.rb

@@ -15,7 +15,8 @@ module SProc
     ].freeze
   end
 
-  # The possible states of this subprocess
+  # The available execution states of a the subprocess
+  # running within an SProc instance.
   module ExecutionState
     NOT_STARTED = 0
     RUNNING = 1
@@ -73,42 +74,6 @@ module SProc
       @env = env
     end
 
-    # Return the execution state of this SubProcess. Note that it is not
-    # identical with the life-cycle of the underlying ProcessStatus object
-    #
-    # @return current ExecutionState
-    def execution_state
-      return ExecutionState::NOT_STARTED if @execution_thread.nil?
-
-      # Count this SubProcess as running as long as the thread
-      # that executes it is alive (this includes book keeping
-      # chores within this class as well)
-      return ExecutionState::RUNNING if @execution_thread.alive?
-
-      status = task_info[:process_status]
-
-      # an execution thread that has run but not generated a task_info
-      # means that we tried to start a process but failed
-      return ExecutionState::FAILED_TO_START if status.nil?
-
-      # a process can terminate for different reasons:
-      # - its done
-      # - an uncaught exception-
-      # - an uncaught signal
-
-      # this should take care of uncaught signals
-      return ExecutionState::ABORTED if status.signaled?
-
-      # If the process completed (either successfully or not)
-      return ExecutionState::COMPLETED if status.exited?
-
-      # We don't currently handle a process that has been stopped...
-      raise NotImplementedError("Unhandled process 'stopped' status!") if status.stopped?
-
-      # We should never come here
-      raise RuntimeError("Unhandled process status: #{status.inspect}")
-    end
-
     # Start the sub-process and block until it has completed.
     #
     #
@@ -147,6 +112,48 @@ module SProc
       task_info
     end
 
+    # Return the execution state of this SubProcess. Note that it is not
+    # identical with the life-cycle of the underlying ProcessStatus object
+    #
+    # @return current ExecutionState
+    def execution_state
+      return ExecutionState::NOT_STARTED if @execution_thread.nil?
+
+      # Count this SubProcess as running as long as the thread
+      # that executes it is alive (this includes book keeping
+      # chores within this class as well)
+      return ExecutionState::RUNNING if @execution_thread.alive?
+
+      status = task_info[:process_status]
+
+      # an execution thread that has run but not generated a task_info
+      # means that we tried to start a process but failed
+      return ExecutionState::FAILED_TO_START if status.nil?
+
+      # a process can terminate for different reasons:
+      # - its done
+      # - an uncaught exception-
+      # - an uncaught signal
+
+      # this should take care of uncaught signals
+      return ExecutionState::ABORTED if status.signaled?
+
+      # If the process completed (either successfully or not)
+      return ExecutionState::COMPLETED if status.exited?
+
+      # We don't currently handle a process that has been stopped...
+      raise NotImplementedError("Unhandled process 'stopped' status!") if status.stopped?
+
+      # We should never come here
+      raise RuntimeError("Unhandled process status: #{status.inspect}")
+    end
+
+    # @return the TaskInfo representing this SubProcess, nil if
+    #         process has not started
+    def task_info
+      @runner.task_info
+    end
+
     # blocks until all processes in the given array are completed/aborted.
     #
     # the implementation polls each process after each given poll interval
@@ -211,12 +218,6 @@ module SProc
       all_proc
     end
 
-    # @return the TaskInfo representing this SubProcess, nil if
-    #         process has not started
-    def task_info
-      @runner.task_info
-    end
-
     # return processes that are no longer running
     def self.get_finished(running_proc)
       running_proc.select do |p|
@@ -228,6 +229,8 @@ module SProc
 
     private
 
+    # a helper method that supports both synch/async execution
+    # depending on the supplied args
     def exec(synch, env, cmd, *args, **opts)
       raise 'Subprocess already running!' unless @execution_thread.nil? || !@execution_thread.alive?
 

data/lib/sproc/osinfo.rb

@@ -0,0 +1,55 @@
+require 'rbconfig'
+
+# helper methods to find out os and execution environment
+module SProc
+  module OSInfo
+    # the supported exec environments
+    module OS
+      WINDOWS = 0
+      LINUX = 1
+      MINGW = 2
+      CYGWIN = 3
+      OSX = 4
+      BSD = 5
+      UNKNOWN = 100
+    end
+
+    # returns the current execution environment
+    def self.os_context
+      case RbConfig::CONFIG['host_os']
+      when /mswin/ then OS::WINDOWS
+      when /mingw/ then OS::MINGW
+      when /cygwin/ then OS::CYGWIN
+      when /darwin/ then OS::OSX
+      when /linux/ then OS::LINUX
+      when /bsd/ then OS::BSD
+      else OS::UNKNOWN
+      end
+    end
+
+    # return the current underlying operating system
+    def self.host_os
+      if [OS::WINDOWS, OS::MINGW, OS::CYGWIN].include?(os_context)
+        OS::WINDOWS
+      else
+        os_context
+      end
+    end
+
+    def on_windows?
+      OSInfo.host_os == OS::WINDOWS
+    end
+
+    def on_linux?
+      OSInfo.os_context == OS::LINUX
+    end
+
+    def on_bsd?
+      OSInfo.os_context == OS::BSD
+    end
+
+    def on_osx?
+      OSInfo.os_context == OS::OSX
+    end
+  end
+end

data/lib/sproc/reporting.rb

@@ -0,0 +1,196 @@
+require_relative 'core'
+
+# This module is written to provide sub-process
+# execution with some human readable logging of process start/stop/errors
+#
+# It wraps SProc instances and execution with calls to logging methods
+# that tries to make the resulting log user friendly
+module SProc
+  module Reporting
+    class << self
+      attr_accessor :logger
+    end
+
+    def logger
+      Reporting.logger
+    end
+
+    # Run a process synchronuously via the native shell and log
+    # output suitable for a build log
+    #
+    # @param cmd_name   a String containing a descriptive
+    #                        name for what the process will do.
+    # @param cmd, args, opts see SProc.exec_sync
+    #
+    # @return                the SProc instance containing the completed process
+    def report_sync(cmd_name, cmd, *args, **opts)
+      p = create_proc_and_log(cmd_name,
+                              ShellType::NONE, :exec_sync,
+                              cmd, args, opts)
+      report_completed(p)
+      p
+    end
+
+    # Run a process asynchronuously via the native shell and log
+    # output suitable for a build log
+    #
+    # @param cmd_name   a String containing a descriptive
+    #                        name for what the process will do.
+    # @param cmd, args, opts see SProc.exec_sync
+    #
+    # @return                the created SProc instance
+    def report_async(cmd_name, cmd, *args, **opts)
+      create_proc_and_log(cmd_name,
+                          ShellType::NONE, :exec_async,
+                          cmd, args, opts)
+    end
+
+    # Run a process asynchronuously via the Bash shell and log
+    # output suitable for a build log
+    #
+    # @param cmd_name   a String containing a descriptive
+    #                        name for what the process will do.
+    # @param cmd, args, opts see SProc.exec_sync
+    #
+    # @return                the created SProc instance
+    def report_async_within_bash(cmd_name, cmd, *args, **opts)
+      create_proc_and_log(cmd_name,
+                          ShellType::BASH, :exec_async,
+                          cmd, args, opts)
+    end
+
+    # Log output from a completed/aborted process
+    #
+    # @param process   the SProc instance that has run
+    # @return          true/false corresponding to process success
+    def report_completed(process)
+      friendly_name = if @log_friendly_name_map&.key?(process)
+                  "#{@log_friendly_name_map[process]}"
+                else
+                  process.task_info[:cmd_str][0,10] + "..."
+                end
+      started_ok = true
+      case process.execution_state
+      when ExecutionState::COMPLETED
+        process.exit_zero? && log_completed_ok(friendly_name, process.task_info)
+        !process.exit_zero? && log_completed_err(friendly_name, process.task_info)
+      when ExecutionState::ABORTED
+        log_aborted(friendly_name, process.task_info)
+        started_ok = false
+      when ExecutionState::FAILED_TO_START
+        log_failed_start(friendly_name, process.task_info)
+        started_ok = false
+      else
+        log_unexpected(friendly_name, process.task_info)
+      end
+      started_ok && process.exit_zero?
+    end
+
+    private
+
+    def create_proc_and_log(cmd_name, type, method, cmd, args, opts)
+      log_start(cmd_name, type, method, cmd, args, **opts)
+      p = SProc.new(type: type).send(method, cmd, args, **opts)
+      @log_friendly_name_map ||= {}
+      @log_friendly_name_map[p] = cmd_name
+      p
+    end
+
+    def log_method_result_ok(friendly_name, delta)
+      logger.info do
+        "#{friendly_name} completed successfully after #{delta.round(3)}s"
+      end
+    end
+
+    def log_method_result_error(friendly_name_method, delta, exc)
+      logger.error do
+        "#{friendly_name_method} aborted by #{exc.class} after #{delta.round(3)}s\n"\
+        "Exception info: #{exc.message}"
+      end
+
+      logger.debug do
+        exc.backtrace.to_s
+      end
+    end
+
+    def log_start(cmd_name, type, method, cmd, *args, **opts)
+      logger.info do
+        async_str = method == :exec_async ? 'asynchronuously' : 'synchronuously'
+        type_str = type == ShellType::NONE ? 'without shell' : 'within the bash shell'
+        "'#{cmd_name}' executing #{async_str} #{type_str}..."
+      end
+      logger.debug do
+        msg = String.new("Starting #{cmd}")
+        msg << " with args: #{args.flatten.inspect}" unless args.nil? || args.empty?
+        msg << " and opts: #{opts.inspect}" unless opts.nil? || opts.empty?
+        msg
+      end
+    end
+
+    def log_one_dll(regex, cmd_str, time)
+      m = regex.match(cmd_str)
+      s = m.nil? ? cmd_str : m[1]
+      max = 45
+      s = s.length > max ? s.slice(0..max - 1) : s.ljust(max)
+      logger.info { "#{s} took #{time.round(3)}s." }
+    end
+
+    def log_aborted(friendly_name, p_info)
+      logger.error do
+        "'#{friendly_name}' aborted!\n"\
+        "When running: #{p_info[:cmd_str]}\n"\
+        "#{merge_proc_output(p_info)}"\
+        "#{p_info[:process_status] unless p_info[:process_status].nil?}"
+      end
+    end
+
+    def log_failed_start(friendly_name, p_info)
+      logger.error do
+        "'#{friendly_name}' not run!\n"\
+        "Could not start process using: #{p_info[:cmd_str]}\n"\
+        "#{merge_proc_output(p_info)}"
+      end
+    end
+
+    def log_completed_ok(friendly_name, p_info)
+      logger.info do
+        "'#{friendly_name}' completed successfully after #{p_info[:wall_time].round(3)}s"
+      end
+      logger.debug do
+        "Cmd: #{p_info[:cmd_str]}"
+      end
+    end
+
+    def log_completed_err(friendly_name, p_info)
+      logger.error do
+        "'#{friendly_name}' completed with exit code "\
+        "#{p_info[:process_status].exitstatus}\n"\
+        "When running: #{p_info[:cmd_str]}\n"\
+        "after #{p_info[:wall_time].round(3)}s\n"\
+        "#{merge_proc_output(p_info)}"
+      end
+    end
+
+    def log_unexpected(friendly_name, p_info)
+      logger.error do
+        "'#{friendly_name}' caused unexpected error!"\
+        ' Trying to display info on a running process'\
+        "(#{p_info[:cmd_str]})"
+      end
+    end
+
+    # @return String with sections for each non-empty output stream
+    #                and exception messages
+    def merge_proc_output(p_info)
+      inf_str = %i[stdout stderr].collect do |sym|
+        next('') if p_info[sym].empty?
+
+        "--- #{sym} ---\n#{p_info[sym]}"
+      end.join("\n")
+
+      exc = p_info[:exception]
+      inf_str << "--- exception ---\n#{exc}\n" unless exc.nil?
+      inf_str
+    end
+  end
+end

data/lib/sproc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SProc
-  VERSION = "0.3.0"
+  VERSION = "0.6.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sproc
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Anders Rillbert
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-27 00:00:00.000000000 Z
+date: 2021-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -43,7 +43,8 @@ files:
 - bin/setup
 - lib/sproc.rb
 - lib/sproc/core.rb
-- lib/sproc/utils.rb
+- lib/sproc/osinfo.rb
+- lib/sproc/reporting.rb
 - lib/sproc/version.rb
 - sproc.gemspec
 homepage: https://github.com/rillbert/sproc

data/lib/sproc/utils.rb

@@ -1,53 +0,0 @@
-require 'rbconfig'
-
-# utility to find out info about our execution environment
-module OSInfo
-  # the supported exec environments
-  module OS
-    WINDOWS = 0
-    LINUX = 1
-    MINGW = 2
-    CYGWIN = 3
-    OSX = 4
-    BSD = 5
-    UNKNOWN = 100
-  end
-
-  # returns the current execution environment
-  def self.os_context
-    case RbConfig::CONFIG['host_os']
-    when /mswin/ then OS::WINDOWS
-    when /mingw/ then OS::MINGW
-    when /cygwin/ then OS::CYGWIN
-    when /darwin/ then OS::OSX
-    when /linux/ then OS::LINUX
-    when /bsd/ then OS::BSD
-    else OS::UNKNOWN
-    end
-  end
-
-  # return the current underlying operating system
-  def self.host_os
-    if [OS::WINDOWS, OS::MINGW, OS::CYGWIN].include?(os_context)
-      OS::WINDOWS
-    else
-      os_context
-    end
-  end
-
-  def on_windows?
-    host_os == OS::WINDOWS
-  end
-
-  def on_linux?
-    os_context == OS::LINUX
-  end
-
-  def on_bsd?
-    os_context == OS::BSD
-  end
-
-  def on_osx?
-    os_context == OS::OSX
-  end
-end