https://github.com/enkessler/childprocess

Cross-platform Ruby library for managing child processes.
https://github.com/enkessler/childprocess

Keywords from Contributors

rubygems activerecord mvc activejob rspec rack cucumber ruby-gem deployment polyglot-release

Last synced: about 16 hours ago
JSON representation

Repository metadata

Cross-platform Ruby library for managing child processes.

Host: GitHub
URL: https://github.com/enkessler/childprocess
Owner: enkessler
License: mit
Created: 2010-10-08T02:44:39.000Z (about 15 years ago)
Default Branch: master
Last Pushed: 2024-08-06T06:37:24.000Z (over 1 year ago)
Last Synced: 2025-12-08T10:29:24.333Z (9 days ago)
Language: Ruby
Homepage:
Size: 484 KB
Stars: 582
Watchers: 6
Forks: 77
Open Issues: 0
Releases: 5
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

childprocess

This gem aims at being a simple and reliable solution for controlling
external programs running in the background on any Ruby / OS combination.

The code originated in the selenium-webdriver gem, but should prove useful as
a standalone library.

Gem Version

Requirements

Ruby 2.4+, JRuby 9+

Usage

The object returned from ChildProcess.build will implement ChildProcess::AbstractProcess.

Basic examples

process = ChildProcess.build("ruby", "-e", "sleep")

# inherit stdout/stderr from parent...
process.io.inherit!

# ...or pass an IO
process.io.stdout = Tempfile.new("child-output")

# modify the environment for the child
process.environment["a"] = "b"
process.environment["c"] = nil

# set the child's working directory
process.cwd = '/some/path'

# start the process
process.start

# check process status
process.alive?    #=> true
process.exited?   #=> false

# wait indefinitely for process to exit...
process.wait
process.exited?   #=> true

# get the exit code
process.exit_code #=> 0

# ...or poll for exit + force quit
begin
  process.poll_for_exit(10)
rescue ChildProcess::TimeoutError
  process.stop # tries increasingly harsher methods to kill the process.
end

Advanced examples

Output to pipe

r, w = IO.pipe

begin
  process = ChildProcess.build("sh" , "-c",
                               "for i in {1..3}; do echo $i; sleep 1; done")
  process.io.stdout = w
  process.start # This results in a subprocess inheriting the write end of the pipe.

  # Close parent's copy of the write end of the pipe so when the child
  # process closes its write end of the pipe the parent receives EOF when
  # attempting to read from it. If the parent leaves its write end open, it
  # will not detect EOF.
  w.close

  thread = Thread.new do
    begin
      loop do
        print r.readpartial(16384)
      end
    rescue EOFError
      # Child has closed the write end of the pipe
    end
  end

  process.wait
  thread.join
ensure
  r.close
end

Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.

Write to stdin

process = ChildProcess.build("cat")

out      = Tempfile.new("duplex")
out.sync = true

process.io.stdout = process.io.stderr = out
process.duplex    = true # sets up pipe so process.io.stdin will be available after .start

process.start
process.io.stdin.puts "hello world"
process.io.stdin.close

process.poll_for_exit(exit_timeout_in_seconds)

out.rewind
out.read #=> "hello world\n"

Pipe output to another ChildProcess

search           = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
search.duplex    = true # sets up pipe so search.io.stdin will be available after .start
search.io.stdout = $stdout
search.start

listing           = ChildProcess.build("ps", "aux")
listing.io.stdout = search.io.stdin
listing.start
listing.wait

search.io.stdin.close
search.wait

Ensure entire process tree dies

By default, the child process does not create a new process group. This means there's no guarantee that the entire process tree will die when the child process is killed. To solve this:

process = ChildProcess.build(*args)
process.leader = true
process.start

Detach from parent

process = ChildProcess.build("sleep", "10")
process.detach = true
process.start

Invoking a shell

As opposed to Kernel#system, Kernel#exec et al., ChildProcess will not automatically execute your command in a shell (like /bin/sh or cmd.exe) depending on the arguments.
This means that if you try to execute e.g. gem executables (like bundle or gem) or Windows executables (with .com or .bat extensions) you may see a ChildProcess::LaunchError.
You can work around this by being explicit about what interpreter to invoke:

ChildProcess.build("cmd.exe", "/c", "bundle")
ChildProcess.build("ruby", "-S", "bundle")

Log to file

Errors and debugging information are logged to $stderr by default but a custom logger can be used instead.

logger = Logger.new('logfile.log')
logger.level = Logger::DEBUG
ChildProcess.logger = logger

Caveats

With JRuby on Unix, modifying ENV["PATH"] before using childprocess could lead to 'Command not found' errors, since JRuby is unable to modify the environment used for PATH searches in java.lang.ProcessBuilder. This can be avoided by setting ChildProcess.posix_spawn = true.
With JRuby on Java >= 9, the JVM may need to be configured to allow JRuby to access neccessary implementations; this can be done by adding --add-opens java.base/java.io=org.jruby.dist and --add-opens java.base/sun.nio.ch=org.jruby.dist to the JAVA_OPTS environment variable that is used by JRuby when launching the JVM.

Implementation

ChildProcess 5+ uses Process.spawn from the Ruby core library for maximum portability.

Note on Patches/Pull Requests

Fork it
Create your feature branch (off of the development branch)
git checkout -b my-new-feature dev
Commit your changes
git commit -am 'Add some feature'
Push to the branch
git push origin my-new-feature
Create new Pull Request

Publishing a New Release

When publishing a new gem release:

Ensure latest build is green on the dev branch
Ensure CHANGELOG is updated
Ensure version is bumped following Semantic Versioning
Merge the dev branch into master: git checkout master && git merge dev
Ensure latest build is green on the master branch
Build gem from the green master branch: git checkout master && gem build childprocess.gemspec
Push gem to RubyGems: gem push childprocess-<VERSION>.gem
Tag commit with version, annotated with release notes: git tag -a <VERSION>

Copyright

Owner metadata

Name: Eric Kessler
Login: enkessler
Email:
Kind: user
Description:
Website:
Location: Columbus, Ohio
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/690565?v=4
Repositories: 41
Last ynced at: 2023-04-22T17:44:41.213Z
Profile URL: https://github.com/enkessler

GitHub Events

Total

Watch event: 2

Last Year

Watch event: 2

Committers metadata

Last synced: 2 days ago

Total Commits: 515
Total Committers: 49
Avg Commits per committer: 10.51
Development Distribution Score (DDS): 0.359

Commits in past year: 0
Committers in past year: 0
Avg Commits per committer in past year: 0.0
Development Distribution Score (DDS) in past year: 0.0

Name	Email	Commits
Jari Bakken	j**n@g**m	330
Eric Kessler	m**8@g**m	49
Shane da Silva	s**e@d**o	38
Matt Fletcher	f**r@a**m	9
Marc Siegel	m**c@u**m	9
Chris Schmich	s**h@g**m	8
Ryan Davis	r**y@z**m	4
Pete Higgins	p**e@p**g	4
Benoit Daloze	e**p@g**m	4
Brent Cook	b**k@r**m	4
James Stocks	j**s@p**m	3
Jan Graichen	jg@a****e	3
Jarl Friis	j**l@s**k	3
Luke Imhoff	l**f@r**m	3
Craig Gumbley	c**y@g**m	2
Hans de Graaff	h**s@d**g	2
Mike Sassak	m**k@g**m	2
Nick Sieger	n**k@n**m	2
Nicolas Leger	n****r	2
Olle Jonsson	o**n@g**m	2
Ry Biesemeyer	r**r@e**o	2
sophia	s**5@g**m	2
Matt Brictson	m**t@1**g	2
michael	m**l@i**t	1
iain	i**n@i**l	1
Arve Knudsen	a**k@m**m	1
Chris Knadler	t**k@g**m	1
Mate Farkas	m**s@s**u	1
Mike Gunderloy	M**1@l**m	1
Zack Mariscal	z**l@g**m	1
and 19 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 3 days ago

Total issues: 60
Total pull requests: 54
Average time to close issues: over 1 year
Average time to close pull requests: 3 months
Total issue authors: 51
Total pull request authors: 34
Average comments per issue: 4.8
Average comments per pull request: 6.89
Merged pull request: 35
Bot issues: 0
Bot pull requests: 0

Past year issues: 0
Past year pull requests: 0
Past year average time to close issues: N/A
Past year average time to close pull requests: N/A
Past year issue authors: 0
Past year pull request authors: 0
Past year average comments per issue: 0
Past year average comments per pull request: 0
Past year merged pull request: 0
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/enkessler/childprocess

Top Issue Authors

JoshCheek (3)
ms-ati (3)
ghost (2)
jmthomas (2)
voxik (2)
titusfortner (2)
hferentschik (2)
Carey99 (1)
jdelStrother (1)
phil-monroe (1)
eregon (1)
garybunofsky (1)
ronaldosolarevisky1 (1)
jordansissel (1)
copiousfreetime (1)

Top Pull Request Authors

sds (12)
eregon (6)
mattbrictson (4)
ms-ati (3)
olleolleolle (2)
DavidS (2)
james-stocks (2)
MSP-Greg (1)
amatsuda (1)
soapy1 (1)
graaff (1)
zmariscal (1)
zenspider (1)
ghost (1)
jdelStrother (1)

Top Issue Labels

question (8)
bug (8)
windows (7)
feature-request (5)
help wanted (3)

Top Pull Request Labels

bug (9)
help wanted (1)
work in progress (1)

Package metadata

Total packages: 3
Total downloads:
- rubygems: 563,688,301 total
Total docker downloads: 2,227,631,852
Total dependent packages: 182 (may contain duplicates)
Total dependent repositories: 307,829 (may contain duplicates)
Total versions: 212
Total maintainers: 3

gem.coop: childprocess

This gem aims at being a simple and reliable solution for controlling external programs running in the background on any Ruby / OS combination.

Homepage: https://github.com/enkessler/childprocess
Documentation: http://www.rubydoc.info/gems/childprocess/
Licenses: MIT
Latest release: 5.1.0 (published over 1 year ago)
Last Synced: 2025-12-15T02:24:39.600Z (2 days ago)
Versions: 72
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 281,851,639 Total
Docker Downloads: 1,113,815,926
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.041%
- Docker downloads count: 0.078%
- Downloads: 0.085%
Maintainers (3)
- sds
- jarib
- enkessler

rubygems.org: childprocess