exeggutor 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ef72410040189a5e3d92f9112a65ddf167d08196047136da03e5471fbce10c6
-  data.tar.gz: 2767a58074b611c9b47448313f1eb483648b8b81336fd7e49998cece6ca11ed6
+  metadata.gz: f12efae289d93904fde9c9f64edda09e2b085805969648d3345c4054597032fc
+  data.tar.gz: 35d7e49dd376fc0a03dc70c02b61c947bbbc0d27c0ba31c16250b4bce9332b74
 SHA512:
-  metadata.gz: a681829d986c9466675547079d53d90420e9a26b1cf71ce7987a48c766e3400510009595e6e8dec6c73e15b20c2a618e3233367c47827ecfa53ebe8b040a6149
-  data.tar.gz: '0329cd3a8c536474c5a2090c7a1f049c01c571b9d6038fe013fe9946277884587fef568839f70303c813869c05a510da0f323eeb24ce1b1dbdceefa101dc1e67'
+  metadata.gz: 9d627a0d4a40b7a235643f57a8a67836c9f016ff66c1473da7e629f30cbd2cb084ae91ed9a76fd8ac931f7fd95424331de6ebe8a5f918ac8eba48d425ccf261d
+  data.tar.gz: 16e0d72b24bc2b0da0a4522c0e90720eefbcf18c28cdae17daea1d9ad2bdc76880769040517763bdc90c2fd62df85ddbd4a6a183f2c44acadd185fc8f9e7392c

data/lib/exeggutor.rb

@@ -2,19 +2,112 @@ 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.
@@ -39,73 +132,70 @@ 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
+  # @private
+  def self.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_stream.write(stdin_data) if stdin_data
-    stdin_stream.close
+    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_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
-
-    stderr_thread = Thread.new do
-      while (line = stderr_stream.gets)
-        stderr_str << line
-        warn line if show_stderr
+    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
+      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
@@ -114,20 +204,34 @@ module Exeggutor
   end
 end
 
-# Executes a command with the provided arguments and options
+# 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 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 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(...)
+  Exeggutor::exeg(...)
+end
+
+# 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 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.
+# @return [ProcessHandle]
 #
 # @raise [ProcessError] If the command fails and `can_fail` is false.
-def run!(...)
-  Exeggutor::run!(...)
+def exeg_async(...)
+  Exeggutor::ProcessHandle.new(...)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exeggutor
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 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