exeggutor 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b9eb0de91468b1ba1d04da72cac44b57eaadd3553719d86910d71f88af67746
-  data.tar.gz: 77713dec1ae04c17322d25563abf517dc406c34f61661e1fd483abf9a307f123
+  metadata.gz: f12efae289d93904fde9c9f64edda09e2b085805969648d3345c4054597032fc
+  data.tar.gz: 35d7e49dd376fc0a03dc70c02b61c947bbbc0d27c0ba31c16250b4bce9332b74
 SHA512:
-  metadata.gz: edfbd0cbe10c2b38812b8a92adfa91566cdd5f4823a4d4e9030a516c7b0c352c465796c7c30b78744db33501d3cf832acf1570076aa47a1db0826621a5d0ab16
-  data.tar.gz: a7bdcd0f7f915dfce050b7cb84ec3ffe92ac46304524e2f51440eeef02417209458f35562256b7e74807795501d893a24eed97cf947481686d5f7bd3a1c7e064
+  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,83 +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
 
-  # Executes a command with the provided arguments and options
-  #
-  # @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,
-  #        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 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
-
-    stderr_stream.sync = true # Match terminals more closely
-
-    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
+  # @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_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
+      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
@@ -124,6 +204,34 @@ module Exeggutor
   end
 end
 
-def run!(...)
-  Exeggutor::run!(...)
+# 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(...)
+  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 [ProcessHandle]
+#
+# @raise [ProcessError] If the command fails and `can_fail` is false.
+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.0
+  version: 0.1.3
 platform: ruby
 authors:
 - Michael Eisel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-23 00:00:00.000000000 Z
+date: 2025-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest