Description
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.
childprocess alternatives and similar gems
Based on the "Processes and Threads" category.
Alternatively, view childprocess alternatives based on common mentions on social networks and blogs.
SaaSHub - Software Alternatives and Reviews
* Code Quality Rankings and insights are calculated and provided by Lumnify.
They vary from L1 to L5 with "L5" being the highest.
Do you think we are missing an alternative of childprocess or a related project?
README
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.
Requirements
- Ruby 2.4+, JRuby 9+
Windows users must ensure the ffi
gem (>= 1.0.11
) is installed in order to use ChildProcess.
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 fork, inheriting the write end of the pipe.
# Close parent's copy of the write end of the pipe so when the (forked) 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
Prefer posix_spawn on *nix
If the parent process is using a lot of memory, fork+exec
can be very expensive. The posix_spawn()
API removes this overhead.
ChildProcess.posix_spawn = true
process = ChildProcess.build(*args)
To be able to use this, please make sure that you have the ffi
gem installed.
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 injava.lang.ProcessBuilder
. This can be avoided by settingChildProcess.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 theJAVA_OPTS
environment variable that is used by JRuby when launching the JVM.
Implementation
How the process is launched and killed depends on the platform:
- Unix :
fork + exec
(orposix_spawn
if enabled) - Windows :
CreateProcess()
and friends - JRuby :
java.lang.{Process,ProcessBuilder}
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](CHANGELOG.md) is updated
- Ensure [version is bumped](lib/childprocess/version.rb) following Semantic Versioning
- Merge the
dev
branch intomaster
: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
Copyright (c) 2010-2015 Jari Bakken. See [LICENSE](LICENSE) for details.
*Note that all licence references and agreements mentioned in the childprocess README section above
are relevant to that project's source code only.