sproc 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8938c9977d79ffd99b2526dc698d66f33c0afc225121307a7cbf79fe9284acdb
-  data.tar.gz: 0fcd34ab808b76a121a581443b0bf9c075e8bf92633a112c406b11b11691b9ab
+  metadata.gz: bec73dcb32037bd849d44167aea25574b4575a704fc5fb88e822001667c2080a
+  data.tar.gz: 3ebc7e7a8be82a6e69c59fcbc29881b365e6af37c9652dc3065a8fa320bfe7b8
 SHA512:
-  metadata.gz: e4da5cce84127eb2b3fda62ba9cb893b588ad1e68b173ad8ef558d8c7f4945c089c74dea20e7be62e7e685bd7efbcf91a6d0616bcc413a7fb4663731151c25da
-  data.tar.gz: 7abf027ed86e29fbc531698feec84c318fda64d3138fa3e22bce81c1f2ef7a79b73aa255274de5f0265453c8df59964a616b912cb41cb55b8e692cd36b0d1fae
+  metadata.gz: 5fb7cfb22432f1a81913dfb07faf969306672f3e436b4e19451928934e169c256dd0b474f5d6ae653f49022b8a21f683bf2e31ebc808c22c7ce8463552c2298b
+  data.tar.gz: 03bb0859af3885655a8c26cdfce0360701b9f8aee111bf6228424f0cb63ed869814677292a845eda6f9059a2383732744ba70b33f1604c582aec67cb02605d94

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/reporter.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'
+                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.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sproc
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 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,6 +43,7 @@ files:
 - bin/setup
 - lib/sproc.rb
 - lib/sproc/core.rb
+- lib/sproc/reporter.rb
 - lib/sproc/utils.rb
 - lib/sproc/version.rb
 - sproc.gemspec