Skip to content
This repository

Asynchronous multiplatform popen implementation relying on EventMachine

README.rdoc

RightPopen

Maintained by the RightScale Teal Team

DESCRIPTION

Synopsis

RightPopen allows running external processes aynchronously while still capturing their standard and error outputs. It relies on EventMachine for most of its internal mechanisms. The Linux implementation is valid for any Linux platform but there is also a native implementation for Windows platforms.

Refer to the wiki (github.com/rightscale/right_popen/wikis) for up-to-date documentation.

Also use the built-in issues tracker (github.com/rightscale/right_popen/issues) to report issues.

Maintained by the RightScale Teal Team

USAGE

Simple Example

require 'rubygems'
require 'right_popen'

@stdout_text = ""
@stderr_text = ""
@exit_status = nil
@pid = nil

def on_pid(pid)
  @pid = pid
end

def on_read_stdout(data)
  @stdout_text << data
end

def on_read_stderr(data)
  @stderr_text << data
end

def on_exit(status)
  @exit_status = status
end

EM.run do
  EM.next_tick do
    command = "ruby -e \"puts 'some stdout text'; $stderr.puts 'some stderr text'\; exit 99\""
    RightScale::RightPopen.popen3_async(
      command,
      :target         => self,
      :environment    => nil,
      :pid_handler    => :on_pid,
      :stdout_handler => :on_read_stdout,
      :stderr_handler => :on_read_stderr,
      :exit_handler   => :on_exit)
  end
  timer = EM::PeriodicTimer.new(0.1) do
    if @exit_status
      timer.cancel
      EM.stop
    end
  end
end

puts "@stdout_text = #{@stdout_text}"
puts "@stderr_text = #{@stderr_text}"
puts "@exit_status.exitstatus = #{@exit_status.exitstatus}"
puts "@pid = #{@pid}"

INSTALLATION

RightPopen can be installed by entering the following at the command prompt:

gem install right_popen

BUILDING

Install the following RubyGems required for building:

  • rake

The Windows implementation relies on a native C module which must currently be built using the MSVC 6.0 compiler due to a dependency on the standard libraries FILE struct provided by the “msvcrt.dll”.

The gem can be built on Linux or Windows platforms and will produce separate gem files depending on current platform. Run the following command from the directory containing the “Rakefile”:

rake build_binary_gem

TESTING

Install the following RubyGems required for testing:

  • rspec

The build can be tested using the RSpec gem. Create a link to the installed “spec” in your Ruby/bin directory (or ensure the bin directory is on the PATH under Windows) and run the following command from the gem directory to execute the RightPopen tests:

rake spec

LICENSE

RightPopen

Copyright

Copyright © 2010-2013 RightScale, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.