exeggutor 0.1.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ef72410040189a5e3d92f9112a65ddf167d08196047136da03e5471fbce10c6
-  data.tar.gz: 2767a58074b611c9b47448313f1eb483648b8b81336fd7e49998cece6ca11ed6
+  metadata.gz: 8d90faa7fb5d339db88d49c085d3a878d92f274595ea95e5a0efead535b3ad48
+  data.tar.gz: 7291380ab60f90b974af5e7f32127d1cb45e567bb17455e9978e31ce166fe744
 SHA512:
-  metadata.gz: a681829d986c9466675547079d53d90420e9a26b1cf71ce7987a48c766e3400510009595e6e8dec6c73e15b20c2a618e3233367c47827ecfa53ebe8b040a6149
-  data.tar.gz: '0329cd3a8c536474c5a2090c7a1f049c01c571b9d6038fe013fe9946277884587fef568839f70303c813869c05a510da0f323eeb24ce1b1dbdceefa101dc1e67'
+  metadata.gz: 8f9d68fa39c285bf2d838331fe5ab795c8b606e1ebf694a0df42c1147b6d979d3080959b3c601eff396e04a2790e2e3540a7f8bb66e907bf54c602aacec9c719
+  data.tar.gz: 541d557d0340ede5b74a99e2200548ce253e155c7e8af9e55e57fecca5c7346b5cb74520ba83e995eec1d18683215bb64c93b6d0e3bf5fa93b68fde06d3a3814

data/lib/exeggutor.rb

@@ -2,19 +2,113 @@ require 'open3'
 require 'shellwords'
 
 module Exeggutor
+
+  # A handle to a process, with IO handles to communicate with it
+  # and a {ProcessResult} object when it's done. It's largely similar to the array
+  # of 4 values return by Open3.popen3. However, it doesn't suffer from that library's
+  # dead-locking issue. For example, even if lots of data has been written to stdout that hasn't been
+  # read, the subprocess can still write to stdout and stderr without blocking
+  class ProcessHandle
+    # @private
+    def initialize(args, env: nil, chdir: nil)
+      @stdin_io, @stdout_io, @stderr_io, @wait_thread = Exeggutor::run_popen3(args, env, chdir)
+
+      # Make the streams as synchronous as possible, to minimize the possibility of a surprising lack
+      # of output
+      @stdout_io.sync = true
+      @stderr_io.sync = true
+
+      @stdout_queue = Queue.new
+      @stderr_queue = Queue.new
+
+      @stdout_pipe_reader, @stdout_pipe_writer = IO.pipe
+      @stderr_pipe_reader, @stderr_pipe_writer = IO.pipe
+
+      @stdout_write_thread = Thread.new do
+        loop do
+          data = @stdout_queue.pop
+          break if !data # Queue is closed
+          @stdout_pipe_writer.write(data)
+        end
+        @stdout_pipe_writer.close
+      end
+
+      @stderr_write_thread = Thread.new do
+        loop do
+          data = @stderr_queue.pop
+          break if !data # Queue is closed
+          @stderr_pipe_writer.write(data)
+        end
+        @stderr_pipe_writer.close
+      end
+
+      # popen3 can deadlock if one stream is written to too much without being read,
+      # so it's important to continuously read from both streams. This is why
+      # we can't just let the user call .gets on the streams themselves
+      @read_thread = Thread.new do
+        remaining_ios = [@stdout_io, @stderr_io]
+        while remaining_ios.size > 0
+          readable_ios, = IO.select(remaining_ios)
+          for readable_io in readable_ios
+            begin
+              data = readable_io.read_nonblock(100_000)
+              if readable_io == @stdout_io
+                @stdout_queue.push(data)
+              else
+                @stderr_queue.push(data)
+              end
+            rescue IO::WaitReadable
+              # Shouldn't usually happen because IO.select indicated data is ready, but maybe due to EINTR or something
+              next
+            rescue EOFError
+              if readable_io == @stdout_io
+                @stdout_queue.close
+              else
+                @stderr_queue.close
+              end
+              remaining_ios.delete(readable_io)
+            end
+          end
+        end
+      end
+    end
+
+    # An object containing process metadata and which can be waited on to wait
+    # until the subprocess ends. Identical to popen3's wait_thr
+    def wait_thr
+      @wait_thread
+    end
+
+    # An IO object for stdin that can be written to
+    def stdin
+      @stdin_io
+    end
+
+    # An IO object for stdout that can be written to
+    def stdout
+      @stdout_pipe_reader
+    end
+
+    # An IO object for stderr that can be written to
+    def stderr
+      @stderr_pipe_reader
+    end
+  end
+
   # Represents the result of a process execution.
   #
   # @attr_reader stdout [String] The standard output of the process.
   # @attr_reader stderr [String] The standard error of the process.
   # @attr_reader exit_code [Integer] The exit code of the process.
   class ProcessResult
-    attr_reader :stdout, :stderr, :exit_code
+    attr_reader :stdout, :stderr, :exit_code, :pid
 
     # @private
-    def initialize(stdout:, stderr:, exit_code:)
+    def initialize(stdout:, stderr:, exit_code:, pid:)
       @stdout = stdout
       @stderr = stderr
       @exit_code = exit_code
+      @pid = pid
     end
 
     # Checks if the process was successful.
@@ -28,7 +122,7 @@ module Exeggutor
   # Represents an error that occurs during a process execution.
   # The error contains a {ProcessResult} object with details about the process.
   #
-  # @attr_reader result [ProcessResult] The result of the process execution.
+  # @attr_reader result {ProcessResult} The result of the process execution.
   class ProcessError < StandardError
     attr_reader :result
 
@@ -39,95 +133,100 @@ module Exeggutor
   end
 
   # @private
-  def self.run_popen3(args, env)
+  def self.run_popen3(args, env, chdir)
     # Use this weird [args[0], args[0]] thing for the case where a command with just one arg is being run
+    opts = {}
+    opts[:chdir] = chdir if chdir
     if env
-      Open3.popen3(env, [args[0], args[0]], *args.drop(1))
+      Open3.popen3(env, [args[0], args[0]], *args.drop(1), opts)
     else
-      Open3.popen3([args[0], args[0]], *args.drop(1))
+      Open3.popen3([args[0], args[0]], *args.drop(1), opts)
     end
   end
 
-  def self.run!(args, can_fail: false, show_stdout: false, show_stderr: false, env: nil, cwd: nil, stdin_data: nil)
-    # TODO: expand "~"? popen3 doesn't expand it by default
-    if cwd
-      stdin_stream, stdout_stream, stderr_stream, wait_thread = Dir.chdir(cwd) { Exeggutor::run_popen3(args, env) }
-    else
-      stdin_stream, stdout_stream, stderr_stream, wait_thread = Exeggutor::run_popen3(args, env)
-    end
-
-    stdin_stream.write(stdin_data) if stdin_data
-    stdin_stream.close
-
-    # Make the streams as synchronous as possible, to minimize the possibility of a surprising lack
-    # of output
-    stdout_stream.sync = true
-    stderr_stream.sync = true
-
-    stdout_str = +''  # Using unfrozen string
-    stderr_str = +''
-
-    # Start readers for both stdout and stderr
-    stdout_thread = Thread.new do
-      while (line = stdout_stream.gets)
-
-        stdout_str << line
-        print line if show_stdout
-      end
-    end
+end
 
-    stderr_thread = Thread.new do
-      while (line = stderr_stream.gets)
-        stderr_str << line
-        warn line if show_stderr
+# Executes a command with the provided arguments and options. Waits for the process to finish.
+#
+# @param args [Array<String>] The command and its arguments as an array.
+# @param can_fail [Boolean] If false, raises a ProcessError on failure.
+# @param show_stdout [Boolean] If true, prints stdout to the console in real-time.
+# @param show_stderr [Boolean] If true, prints stderr to the console in real-time.
+# @param chdir [String, nil] The working directory to run the command in. If nil, uses the current working directory.
+# @param stdin [String, nil] Input data to pass to the command's stdin. If nil, doesn't pass any data to stdin.
+# @param env [Hash{String => String}, nil] A hashmap containing environment variable overrides,
+#        or `nil` if no overrides are desired
+#
+# @return {ProcessResult} An object containing process info such as stdout, stderr, and exit code.
+#
+# @raise {ProcessError} If the command fails and `can_fail` is false.
+def exeg(args, can_fail: false, show_stdout: false, show_stderr: false, env: nil, chdir: nil, stdin_data: nil)
+  raise "args.size must be >= 1" if args.empty?
+
+  stdin_io, stdout_io, stderr_io, wait_thr = Exeggutor::run_popen3(args, env, chdir)
+  stdin_io.write(stdin_data) if stdin_data
+  stdin_io.close
+
+  # Make the streams as synchronous as possible, to minimize the possibility of a surprising lack
+  # of output
+  stdout_io.sync = true
+  stderr_io.sync = true
+
+  stdout = +''
+  stderr = +''
+
+  # Although there could be more code sharing between this and exeg_async, it would either complicate exeg_async's inner workings
+  # or force us to pay the same performance cost that exeg_async does
+  remaining_ios = [stdout_io, stderr_io]
+  while remaining_ios.size > 0
+    readable_ios, = IO.select(remaining_ios)
+    for readable_io in readable_ios
+      begin
+        data = readable_io.read_nonblock(100_000)
+        if readable_io == stdout_io
+          stdout << data
+          $stdout.print(data) if show_stdout
+        else
+          stderr << data
+          $stderr.print(data) if show_stderr
+        end
+      rescue IO::WaitReadable
+        # Shouldn't usually happen because IO.select indicated data is ready, but maybe due to EINTR or something
+        next
+      rescue EOFError
+        remaining_ios.delete(readable_io)
       end
     end
+  end
 
-    # Wait for process completion
-    exit_status = wait_thread.value
-
-    # Ensure all IO is complete
-    stdout_thread.join
-    stderr_thread.join
-
-    # Close open pipes
-    stdout_stream.close
-    stderr_stream.close
-
-    result = ProcessResult.new(
-      stdout: stdout_str.force_encoding('UTF-8'),
-      stderr: stderr_str.force_encoding('UTF-8'),
-      exit_code: exit_status.exitstatus
-    )
-
-    if !can_fail && !result.success?
-      error_str = <<~ERROR_STR
-        Command failed: #{args.shelljoin}
-        Exit code: #{result.exit_code}
-        stdout: #{result.stdout}
-        stderr: #{result.stderr}
-      ERROR_STR
-      raise ProcessError.new(result), error_str
-    end
-
-    result
+  result = ProcessResult.new(
+    stdout: stdout,
+    stderr: stderr,
+    exit_code: wait_thr.value.exitstatus,
+    pid: wait_thr.pid
+  )
+  if !can_fail && !result.success?
+    error_str = <<~ERROR_STR
+      Command failed: #{args.shelljoin}
+      Exit code: #{result.exit_code}
+      stdout: #{result.stdout}
+      stderr: #{result.stderr}
+      pid: #{result.pid}
+    ERROR_STR
+    raise ProcessError.new(result), error_str
   end
+
+  result
 end
 
-# Executes a command with the provided arguments and options
+# Executes a command with the provided arguments and options. Does not wait for the process to finish.
 #
 # @param args [Array<String>] The command and its arguments as an array.
-# @param can_fail [Boolean] If false, raises a ProcessError on failure.
-# @param show_stdout [Boolean] If true, prints stdout to the console in real-time.
-# @param show_stderr [Boolean] If true, prints stderr to the console in real-time.
-# @param cwd [String, nil] The working directory to run the command in. If nil, uses the current working directory.
-# @param stdin_data [String, nil] Input data to pass to the command's stdin. If nil, doesn't pass any data to stdin.
-# @param env_vars [Hash{String => String}, nil] A hashmap containing environment variable overrides,
+# @param chdir [String, nil] The working directory to run the command in. If nil, uses the current working directory.
+# @param env [Hash{String => String}, nil] A hashmap containing environment variable overrides,
 #        or `nil` if no overrides are desired
 #
-# @return [ProcessResult] An object containing process info such as stdout, stderr, and exit code. Waits for the command to complete to return.
-#
-# @raise [ProcessError] If the command fails and `can_fail` is false.
-def run!(...)
-  Exeggutor::run!(...)
+# @return {ProcessHandle}
+def exeg_async(args, env: nil, chdir: nil)
+  Exeggutor::ProcessHandle.new(args, env: env, chdir: chdir)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exeggutor
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.4
 platform: ruby
 authors:
 - Michael Eisel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-25 00:00:00.000000000 Z
+date: 2025-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest