The ProcessExecuter Gem

Gem Version Documentation Change Log Build Status Maintainability Test Coverage Conventional Commits Slack

Usage

Full YARD documentation for this gem is hosted on RubyGems.org. Read below of an overview and several examples.

This gem contains the following important classes:

ProcessExecuter::MonitoredPipe

ProcessExecuter::MonitoredPipe streams data sent through a pipe to one or more writers.

When a new MonitoredPipe is created, a pipe is created (via IO.pipe) and a thread is created which reads data as it is written written to the pipe.

Data that is read from the pipe is written one or more writers passed to MonitoredPipe#initialize.

This is useful for streaming process output (stdout and/or stderr) to anything that has a #write method: a string buffer, a file, or stdout/stderr as seen in the following example:

require 'stringio'
require 'process_executer'

output_buffer = StringIO.new
out_pipe = ProcessExecuter::MonitoredPipe.new(output_buffer)
pid, status = Process.wait2(Process.spawn('echo "Hello World"', out: out_pipe))
output_buffer.string #=> "Hello World\n"

MonitoredPipe#initialize can take more than one writer so that pipe output can be streamed (or teed) to multiple writers at the same time:

require 'stringio'
require 'process_executer'

output_buffer = StringIO.new
output_file = File.open('process.out', 'w')
out_pipe = ProcessExecuter::MonitoredPipe.new(output_buffer, output_file)
pid, status = Process.wait2(Process.spawn('echo "Hello World"', out: out_pipe))
output_file.close
output_buffer.string #=> "Hello World\n"
File.read('process.out') #=> "Hello World\n"

Since the data is streamed, any object that implements #write can be used. For insance, you can use it to parse process output as a stream which might be useful for long XML or JSON output.

ProcessExecuter.spawn

ProcessExecuter.spawn has the same interface as Process.spawn but has two important behaviorial differences:

  1. It blocks until the subprocess finishes
  2. A timeout can be specified using the :timeout option

If the command does not terminate before the timeout, the process is killed by sending it the SIGKILL signal. The returned status object's timeout? attribute will return true. For example:

status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
status.signaled? #=> true
status.termsig #=> 9
status.timeout? #=> true

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add process_executer

If bundler is not being used to manage dependencies, install the gem by executing:

gem install process_executer

Contributing

Reporting Issues

Bug reports and other support requests are welcome on this project's GitHub issue tracker

Developing

Clone the repo, run bin/setup to install dependencies, and then run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Commit message guidelines

All commit messages must follow the Conventional Commits standard. This helps us maintain a clear and structured commit history, automate versioning, and generate changelogs effectively.

To ensure compliance, this project includes:

  • A git commit-msg hook that validates your commit messages before they are accepted.

To activate the hook, you must have node installed and run npm install.

  • A GitHub Actions workflow that will enforce the Conventional Commit standard as part of the continuous integration pipeline.

Any commit message that does not conform to the Conventional Commits standard will cause the workflow to fail and not allow the PR to be merged.

Pull request guidelines

All pull requests must be merged using rebase merges. This ensures that commit messages from the feature branch are preserved in the release branch, keeping the history clean and meaningful.

Releasing

In the root directory of this project with the main branch checked out, run the following command:

create-github-release {major|minor|patch}

Follow the directions given by the create-github-release to publish the new version of the gem.

License

The gem is available as open source under the terms of the MIT License.