progeny 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e16d4fb0220a00c09eba23fc3b5f43cf72facb831a8d70f8afb2e4c48507b964
-  data.tar.gz: 6f852ef9c5fb2f0dafd6a153cc9045b5d37021f189e7da18d2ec137b7d9d3338
+  metadata.gz: 5b4b80a4ad000727e13f154cef131b4299d27eed0ed4f200586defa86c60d829
+  data.tar.gz: 31a7c9a885fc3ada1ff8a66ae85a7400b56a0bcb17c1dca0ee9649eac56d7919
 SHA512:
-  metadata.gz: 2f808a8bcdae021ab23ef31ad18df2c3d39b359f9b3752bc5924e143a00757359e64ff0586c617b1e8908cec1bb5e0f9b1076834edce27595e1733f76ddcdbc6
-  data.tar.gz: 97bbb478f5c1ad1fabd55491784da44562d28d909be6f9c67586643f3e740fc1189e298cb2ea05a3ae46b0726a299f2d1cdba0307e19ffec31c83e3a41e7d049
+  metadata.gz: 15a7df8729f641d566a5b69d388592cbe536177c165c4260954a8a23d57c735d3cb4af242ca958f85de79198b33ffecaaba4551d514e2674720f409f433e930b
+  data.tar.gz: 27049a985faef5bd21a349feaece2480b70eba62b3ed253caf941e48e4af841f79797538e5ffaef78518da90ba13cd96a0db439e9d59b1363ba3cce254e7f991

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0] - 2023-05-05
+
+### Added
+
+- `Progeny::Command#spawn_with_pipes` for easier migration from `posix-spawn`.
+
 ## [0.1.0] - 2023-05-03
 
 - Initial release. Forked `posix-spawn` gem.

data/README.md

@@ -12,10 +12,11 @@ strings and is therefore not well-suited to streaming large quantities of data
 in and out of commands. That said, it has some benefits:
 
  - **Simple** - requires little code for simple stream input and capture.
- - **Internally non-blocking** (using `select(2)`) - handles all pipe hang cases
-   due to exceeding `PIPE_BUF` limits on one or more streams.
- - **Uses Ruby under the hood** - It leverages Ruby's `Open3#popen3` and `Process.spawn`
-   behind the scenes so it's widely supported and consistently getting performance updates.
+ - **Internally non-blocking** (using `select(2)`) - handles all pipe hang
+   cases due to exceeding `PIPE_BUF` limits on one or more streams.
+ - **Uses Ruby under the hood** - It leverages Ruby's `Process.spawn` behind
+   the scenes so it's widely supported and consistently getting performance
+   updates.
 
 `Progeny::Command` takes the [standard `Process::spawn`
 arguments](https://ruby-doc.org/current/Process.html#method-c-spawn) when
@@ -132,10 +133,9 @@ end
 ```
 
 You will need to remove the include statements and replace any use of `#spawn`
-with Ruby's native `Process.spawn` and  `#popen4` with Open3's `#popen3`.
+with Ruby's native `Process.spawn` and  `#popen4` with `Progeny::Command.spawn_with_pipes`
 ```diff
 - require 'posix/spawn'
-+ require 'open3'
 
 class YourSpawnerClass
 - include POSIX::Spawn
@@ -148,16 +148,14 @@ class YourSpawnerClass
 
   def calculate(expression)
 -   pid, in, out, err = popen4('bc')
-+   in, out, err, wait_thr = Open3.popen3('bc')
-+   pid = wait_thr[:pid] # if pid is needed
++   pid, in, out, err = Progeny::Command.spawn_with_pipes('bc')
     in.write(expression)
     in.close
     out.read
   ensure
     [in, out, err].each { |io| io.close if !io.closed? }
--   Process::waitpid(pid)
--   $?
-+   wait_thr.value
+    Process::waitpid(pid)
+    $?
   end
 end
 ```

data/lib/progeny/command.rb

@@ -1,5 +1,3 @@
-require "open3"
-
 module Progeny
   # Progeny::Command includes logic for executing child processes and
   # reading/writing from their standard input, output, and error streams. It's
@@ -123,6 +121,41 @@ module Progeny
       new(*(args + [{ :noexec => true }.merge(options)]))
     end
 
+    # Spawn a child process with all standard IO streams piped in and out of
+    # the spawning process. Supports the standard `Process.spawn` interface.
+    #
+    # Returns a [pid, stdin, stdout, stderr] tuple, where pid is the new
+    # process's pid, stdin is a writeable IO object, and stdout / stderr are
+    # readable IO objects. The caller should take care to close all IO objects
+    # when finished and the child process's status must be collected by a call
+    # to Process::waitpid or equivalent.
+    def self.spawn_with_pipes(*argv)
+      if argv.last.is_a?(Hash)
+        opts = argv.pop.dup
+      else
+        opts = {}
+      end
+
+      ird, iwr = IO.pipe
+      ord, owr = IO.pipe
+      erd, ewr = IO.pipe
+
+      opts = opts.merge(
+          # redirect fds        # close other sides
+          :in  => ird,          iwr  => :close,
+          :out => owr,          ord  => :close,
+          :err => ewr,          erd  => :close
+        )
+      pid = spawn(*(argv + [opts]))
+      [pid, iwr, ord, erd]
+    ensure
+      # we're in the parent, close child-side fds
+      [ird, owr, ewr].each { |fd| fd.close if fd }
+    end
+
+    # All data written to the child process's stdin stream as a String.
+    attr_reader :input
+
     # All data written to the child process's stdout stream as a String.
     attr_reader :out
 
@@ -149,14 +182,14 @@ module Progeny
     # immediately when a new instance of this object is created, or
     # can be called explicitly when creating the Command via `build`.
     def exec!
-      stdin, stdout, stderr, wait_thread = Open3.popen3(@env, *(@argv + [@options]))
-      @pid = wait_thread[:pid]
+      pid, stdin, stdout, stderr = self.class.spawn_with_pipes(@env, *@argv, @options)
+      @pid = pid
 
       # async read from all streams into buffers
       read_and_write(@input, stdin, stdout, stderr, @timeout, @max)
 
-      # wait_thr.value waits for the termination of the process and returns exit status
-      @status = wait_thread.value
+      # wait for the termination of the process and return exit status
+      @status = waitpid(pid)
     rescue Object
       [stdin, stdout, stderr].each { |fd| fd.close rescue nil }
       if @status.nil?
@@ -165,7 +198,7 @@ module Progeny
         else
           ::Process.kill('-TERM', pid) rescue nil
         end
-        @status = wait_thread.value rescue nil
+        @status = waitpid(pid) rescue nil
       end
       raise
     ensure
@@ -268,5 +301,13 @@ module Progeny
 
       [@out, @err]
     end
+
+    # Wait for the child process to exit
+    #
+    # Returns the Process::Status object obtained by reaping the process.
+    def waitpid(pid)
+      Process::waitpid(pid)
+      $?
+    end
   end
 end

data/lib/progeny/version.rb

@@ -1,3 +1,3 @@
 module Progeny
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: progeny
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Luan Vieira
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-03 00:00:00.000000000 Z
+date: 2023-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -77,5 +77,5 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: A popen3 wrapper with a nice interface and extra options.
+summary: A process spawn wrapper with a nice interface and extra options.
 test_files: []