background_process 1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Tim Harper
+
+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.

data/README.textile

@@ -0,0 +1,53 @@
+h1. Background Process
+
+This is like popen4, but provides several convenience methods for interacting 
+with the process. It only works on UNIX and Ruby implementations that support 
+fork and native UNIX I/O streams.
+
+Example:
+
+<pre>
+process = BackgroundProcess.run("sh -c 'sleep 1; exit 1'")
+process.running? # => true
+process.wait # => #<Process::Status: pid=34774,exited(1)>
+process.running? #=> true
+process.exitstatus # => 1
+</pre>
+
+<pre>
+process = BackgroundProcess.run("sh -c 'sleep 1; exit 1'")
+process.kill("KILL") # => true
+process.running? # => false
+process.exitstatus # => nil
+</pre>
+
+<pre>
+process = BackgroundProcess.run("sh -c '
+  echo Service Starting
+  sleep 2
+  echo Service Started 1>&2
+'")
+if process.detect(:stderr, 10) { |line| line.include?("Service Started") }
+  puts "Service was started!"
+else
+  puts "Service failed to start!"
+end
+process.kill
+</pre>
+
+h2. Common signal names
+
+| Name   | id |
+| HUP    | 1  |
+| INT    | 2  |
+| QUIT   | 3  |
+| ABRT   | 6  |
+| KILL   | 9  |
+| ALRM   | 14 |
+| TERM   | 15 |
+| USR1   | 30 |
+| USR2   | 31 |
+
+h2. Author
+
+Tim Harper, on behalf of Lead Media Partners

data/lib/background_process/background_process.rb

@@ -0,0 +1,97 @@
+class BackgroundProcess
+  attr_reader :stdin, :stdout, :stderr, :pid
+
+  # Initialize a BackgroundProcess task. Don't do this.  Use BackgroundProcess.run instead
+  def initialize(pid, stdin, stdout, stderr)
+    @pid, @stdin, @stdout, @stderr = pid, stdin, stdout, stderr
+    ObjectSpace.define_finalizer(self) { kill }
+  end
+
+	# Run a BackgroundProcess
+  def self.run(command, &block)
+    command = sanitize_params(command) if command.is_a?(Array)
+    child_stdin, parent_stdin = IO::pipe
+    parent_stdout, child_stdout = IO::pipe
+    parent_stderr, child_stderr = IO::pipe
+
+    pid = Kernel.fork do
+      [parent_stdin, parent_stdout, parent_stderr].each { |io| io.close }
+
+      STDIN.reopen(child_stdin)
+      STDOUT.reopen(child_stdout)
+      STDERR.reopen(child_stderr)
+
+      [child_stdin, child_stdout, child_stderr].each { |io| io.close }
+
+      exec command
+    end
+
+    [child_stdin, child_stdout, child_stderr].each { |io| io.close }
+    parent_stdin.sync = true
+
+    new(pid, parent_stdin, parent_stdout, parent_stderr)
+  end
+
+  # send a signal to the process. If the processes and running, do nothing.
+  # Valid signals are those in Signal.list. Default is "TERM"
+  def kill(signal = 'TERM')
+    if running?
+      Process.kill(Signal.list[signal], @pid)
+      true
+    end
+  end
+
+  # Sends the interrupt signal to the process. The equivalent of pressing control-C in it.
+  def interrupt
+    kill('INT')
+  end
+
+  # asks the operating system is the process still exists.
+  def running?
+    return false unless @pid
+    Process.getpgid(@pid)
+    true
+  rescue Errno::ESRCH
+    false
+  end
+
+  # waits for the process to finish. Freeze the process so it can rest in peace.
+  # You should call this on every background job you create to avoid a flood of
+  # zombie processes. (Processes won't go away until they are waited on)
+  def wait(timeout = nil)
+    @exit_status ||= Timeout.timeout(timeout) do
+      Process.wait(@pid)
+      $?
+    end
+  rescue Timeout::Error
+    nil
+  end
+
+  # Waits for the process to terminate, and then returns the exit status
+  def exitstatus
+    wait && wait.exitstatus
+  end
+
+  # Calls block each time a line is available in the specified output buffer(s) and returns the first non-false value
+  # By default, both stdout and stderr are monitored.
+  #
+  # Args:
+  # * which: which streams to monitor. valid values are :stdout, :stderr, or :both.
+  # * timeout: Total time in seconds to run detect for. If result not found within this time, abort and return nil. Pass nil for no timeout.
+  # * &block: the block to call.  If block takes two arguments, it will pass both the stream that received the input (an instance of IO, not the symbol), and the line read from the buffer.
+  def detect(which = :both, timeout = nil, &block)
+    streams = case which
+              when :stdout then [stdout]
+              when :stderr then [stderr]
+              when :both   then [stdout, stderr]
+              else raise(ArgumentError, "invalid stream specification: #{which}")
+              end
+    BackgroundProcess::IOHelpers.detect(streams, timeout, &block)
+  end
+
+  protected
+  # It's protected. What do you care? :P
+  def self.sanitize_params(params)
+    params.map { |p| p.gsub(' ', '\ ') }.join(" ")
+  end
+end

data/lib/background_process/io_helpers.rb

@@ -0,0 +1,23 @@
+module BackgroundProcess::IOHelpers
+  extend self
+  def detect(streams = [], timeout = nil, &block)
+    begin
+      Timeout::timeout(timeout) do
+        # Something that should be interrupted if it takes too much time...
+        while true
+          available_streams, _, _ = Kernel.select(streams, nil, nil, 1)
+          available_streams.each do |s|
+            content = s.gets
+            if result = (block.arity == 1 ? yield(content) : yield(s, content))
+              return result
+            end
+          end if available_streams
+        end
+      end
+      true
+    rescue Timeout::Error
+      nil
+    end
+
+  end
+end

data/lib/background_process.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + "/background_process/background_process"
+require File.dirname(__FILE__) + "/background_process/io_helpers"

data/spec/background_process/background_process_spec.rb

@@ -0,0 +1,114 @@
+require 'spec_helper'
+
+describe BackgroundProcess do
+  describe ".run" do
+    it "runs a command and returns a background process with properly attached IO pipes" do
+      process = BackgroundProcess.run("printf 'hi'")
+      process.stdout.readline.should == "hi"
+
+      process = BackgroundProcess.run("printf 'hi' 1>&2")
+      process.stderr.readline.should == "hi"
+
+      process = BackgroundProcess.run(%(sh -c 'read hi; printf "$hi"'))
+      process.stdin.puts "hello, world"
+      process.stdin.flush
+      process.stdout.readline.should == "hello, world"
+    end
+
+    it "accepts an array, and properly handles spaces" do
+      process = BackgroundProcess.run(['sh', '-c', 'printf hi'])
+      process.stdout.readline.should == "hi"
+    end
+  end
+
+  describe "#running?" do
+    it "reports when the process is running" do
+      process = BackgroundProcess.run("sleep 0.1")
+      process.should be_running
+      process.wait
+      sleep 0.1
+      process.should_not be_running
+    end
+  end
+
+  describe "#kill" do
+    it "kills a process" do
+      started_at = Time.now
+      process = BackgroundProcess.run("sleep 4")
+      sleep(0.1)
+      process.kill("KILL")
+      process.wait
+      (Time.now - started_at).should < 4.0
+      process.should_not be_running
+    end
+  end
+
+  describe "#exitstatus" do
+    it "returns the exit status of a process after it exits." do
+      process = BackgroundProcess.run("bash -c 'sleep 1; exit 1'")
+      process.exitstatus.should == 1
+      process.exitstatus.should == 1
+    end
+  end
+
+  describe "#wait" do
+    it "waits for a process with timeout" do
+      process = BackgroundProcess.run("sleep 3")
+      started_waiting = Time.now
+      process.wait(0.5).should be_false
+      (Time.now - started_waiting).should be_close(0.5, 0.1)
+    end
+  end
+
+  describe "#detect" do
+    it "calls the provided block for every line outputted, and returns the first non-false value" do
+      process = BackgroundProcess.run("bash -c 'a=0; while sleep 0.1; do a=$(($a + 1)); echo $a; done'")
+      result = process.detect do |line|
+        "golden" if line.strip == "3"
+      end
+      result.should == "golden"
+      process.kill
+    end
+
+    it "yields the stream if two parameters are provided on the block" do
+      process = BackgroundProcess.run("bash -c 'a=0; while sleep 0.1; do a=$(($a + 1)); echo $a 1>&2; done'")
+      result = process.detect(:both, 1) do |stream, line|
+        "golden" if stream == process.stderr && line.strip == "3"
+      end
+      result.should == "golden"
+      process.kill
+    end
+
+    it "aborts if the provided timeout is reached" do
+      process = BackgroundProcess.run("sleep 2")
+      result = process.detect(:both, 0.1) do |stream, line|
+        true
+      end
+      result.should be_nil
+      process.kill
+    end
+
+    it "monitors the specified stream" do
+      process = BackgroundProcess.run("bash -c 'a=0; while sleep 0.1; do a=$(($a + 1)); echo $a; echo $a 1>&2; done'")
+      output = []
+      process.detect(:stdout) do |line|
+        output << line.to_i
+        true if line.to_i == 3
+      end
+
+      process.detect(:stderr) do |line|
+        output << line.to_i
+        true if line.to_i == 3
+      end
+
+      output.should == [1, 2, 3, 1, 2, 3]
+    end
+
+    it "never yields if nothing occurs on specified streams" do
+      process = BackgroundProcess.run("bash -c 'a=0; while sleep 0.1; do a=$(($a + 1)); echo $a; done'")
+      process.detect(:stderr, 1) do |line|
+        raise(Spec::Expectations::ExpectationNotMetError, "expected to not yield the block")
+      end
+    end
+  end
+end

data/spec/background_process/io_helpers_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+describe BackgroundProcess::IOHelpers do
+  describe "#detect" do
+    it "iterates over the lines from each stream as they are available, and returns when a non-false value is reached" do
+      process = BackgroundProcess.run("bash -c 'a=0; while sleep 0.1; do a=$(($a + 1)); echo $a; echo $a 1>&2; done'")
+      outputs = {:out => [], :err => []}
+
+      result = BackgroundProcess::IOHelpers.detect([process.stderr, process.stdout], 1) do |io, line|
+        outputs[io == process.stderr ? :err : :out] << line.to_i
+        true if outputs.values.map {|o| o.length }.uniq == [5]
+      end
+      outputs[:out].should == (1..5).to_a
+      outputs[:err].should == (1..5).to_a
+      result.should be_true
+    end
+
+    it "gives up after the timeout is reached" do
+      process = BackgroundProcess.run("bash -c 'sleep 2; echo done'")
+      started_at = Time.now
+
+      result = BackgroundProcess::IOHelpers.detect([process.stderr, process.stdout], 0.5) do |io, line|
+        true if line.strip == "done"
+      end
+      result.should be_nil
+      (Time.now - started_at).should < 0.6
+      process.kill
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/../lib/background_process"

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: background_process
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  version: "1.0"
+platform: ruby
+authors: 
+- Tim Harper
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-21 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: A library for spawning and interacting with UNIX processes
+email: 
+- timcharper+bp@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- MIT-LICENSE
+- README.textile
+files: 
+- README.textile
+- MIT-LICENSE
+- lib/background_process/background_process.rb
+- lib/background_process/io_helpers.rb
+- lib/background_process.rb
+- spec/background_process/background_process_spec.rb
+- spec/background_process/io_helpers_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/timcharper/background_process
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.textile
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: background_process
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: background_process
+test_files: 
+- spec/background_process/background_process_spec.rb
+- spec/background_process/io_helpers_spec.rb
+- spec/spec_helper.rb