rspec-multiprocess_runner 0.1.0

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/tmp
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.2.3
+before_install: gem install bundler -v 1.10.6

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.1.0
+
+* Initial version

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rspec-multiprocess_runner.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Collaborative Drug Discovery
+
+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.md

@@ -0,0 +1,111 @@
+# Rspec::MultiprocessRunner
+
+This gem provides a mechanism for running a suite of RSpec tests in multiple
+processes on the same machine, potentially allowing substantial performance
+improvements.
+
+It differs from `parallel-tests` in that it uses a coordinator process to manage
+the workers, hand off work to them, and receive results. This means it can
+dynamically balance the workload among the processors. It also means it can
+provide consolidated results in the console.
+
+It does follow parallel-tests' `TEST_ENV_NUMBER` convention so it's easy to
+switch.
+
+## Benefits
+
+* Running slow (IO-bound) specs in parallel can greatly reduce the wall-clock
+  time needed to run a suite. Even CPU-bound specs can be aided
+* Provides detailed logging of each example as it completes, including the
+  failure message (you don't have to wait until the end to see the failure
+  reason).
+* Detects, kills, and reports spec files that take longer than expected (five
+  minutes by default).
+* Detects and reports spec files that crash (without interrupting the
+  remainder of the suite).
+
+## Limitations
+
+* Only works with RSpec 2. Does not work with RSpec 3.
+* Does not work on Windows or JRuby. Since it relies on `fork(2)`, it probably
+  never will.
+* Does not support RSpec custom formatters.
+* The built-in output format is very verbose — it's intended for CI servers,
+  where more logging is better.
+* Intermediate-quality code. Happy path works, and workers are
+  managed/restarted, but:
+  * There's no test coverage of the runner itself, only auxiliaries.
+  * Does not handle the coordinator process dying (e.g., from `^C`).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rspec-multiprocess_runner'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rspec-multiprocess_runner
+
+## Usage
+
+### Command line
+
+Use `multirspec` to run a bunch of spec files:
+
+    $ multirspec spec
+
+Runs three workers by default — use `-w` to chose another count. `--help` will
+detail the other options.
+
+You can provide options that will be passed to the separate RSpec processes by
+including them after a `--`:
+
+    $ multirspec -w 5 spec -- -b -I ./lib
+
+In this case, each RSpec process would receive the options `-b -I ./lib`. Note
+that not that many RSpec options really make sense to pass this way. In
+particular, file selection and output formatting options are unlikely to work
+the way you expect.
+
+### Rake
+
+There is a rake task wrapper for `multirspec`:
+
+    require 'rspec/multiprocess_runner/rake_task'
+
+    RSpec::MultiprocessRunner::RakeTask.new(:spec) do |t|
+      t.worker_count = 5
+      t.pattern = "spec/**/*_spec.rb"
+    end
+
+See its source for the full list of options.
+
+### Code
+
+Create a coordinator and tell it to run:
+
+    require 'rspec/multiprocess_runner/coordinator'
+
+    worker_count = 4
+    per_file_timeout = 5 * 60    # 5 minutes in seconds
+    rspec_args = %w(--backtrace)
+    files = Dir['**/*_spec.rb']
+
+    coordinator = RSpec::MultiprocessRunner::Coordinator(worker_count, per_file_timeout, rspec_args, files)
+    coordinator.run
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/cdd/rspec-multiprocess_runner.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/TODO.md

@@ -0,0 +1,11 @@
+# Tests
+
+Tricky things which I am manually testing:
+
+* Timing out slow files (as_spec.rb)
+* Recognizing and handling workers that die (ax_spec.rb, x*_spec.rb)
+* Preserving the configuration from spec_helper, etc., across runs (w*_spec.rb)
+
+Need to write automated tests for these (in addition to tests for all the basic
+behavior). Maybe use Cucumber (like RSpec does for acceptance tests) to avoid
+the weirdness of testing rspec within rspec.

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rspec/multiprocess_runner"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/multirspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require 'rspec/multiprocess_runner/command_line_options'
+require 'rspec/multiprocess_runner/coordinator'
+
+options = RSpec::MultiprocessRunner::CommandLineOptions.new.parse(ARGV.dup)
+exit(2) unless options
+
+success = RSpec::MultiprocessRunner::Coordinator.new(
+  options.worker_count,
+  options.file_timeout_seconds,
+  options.rspec_options,
+  options.files_to_run
+).run
+
+exit(success ? 0 : 1)

data/lib/rspec/multiprocess_runner/command_line_options.rb

@@ -0,0 +1,98 @@
+require 'rspec/multiprocess_runner'
+require 'optparse'
+require 'pathname'
+
+module RSpec::MultiprocessRunner
+  # @private
+  class CommandLineOptions
+    attr_accessor :worker_count, :file_timeout_seconds, :rspec_options,
+      :explicit_files_or_directories, :pattern
+
+    def initialize
+      self.worker_count = 3
+      self.file_timeout_seconds = 300
+      self.pattern = "**/*_spec.rb"
+      self.rspec_options = []
+    end
+
+    def parse(command_line_args, error_stream=$stderr)
+      args = command_line_args.dup
+      parser = build_parser
+
+      begin
+        parser.parse!(args)
+      rescue OptionParser::ParseError => e
+        error_stream.puts e.to_s
+        error_stream.puts parser
+        return nil
+      end
+
+      if help_requested?
+        error_stream.puts parser
+        return nil
+      end
+
+      extract_files_and_rspec_options(args)
+      self
+    end
+
+    def files_to_run
+      self.explicit_files_or_directories = %w(.) unless explicit_files_or_directories
+      relative_root = Pathname.new('.')
+      explicit_files_or_directories.map { |path| Pathname.new(path) }.flat_map do |path|
+        if path.file?
+          path.to_s
+        else
+          Dir[path.join(pattern).relative_path_from(relative_root)]
+        end
+      end.sort_by { |path| path.downcase }
+    end
+
+    private
+
+    def help_requested!
+      @help_requested = true
+    end
+
+    def help_requested?
+      @help_requested
+    end
+
+    def build_parser
+      OptionParser.new do |parser|
+        parser.banner = "#{File.basename $0} [options] [files or directories] [-- rspec options]"
+
+        parser.on("-w", "--worker-count COUNT", Integer, "Number of workers to run (default: #{worker_count})") do |n|
+          self.worker_count = n
+        end
+
+        parser.on("-t", "--file-timeout SECONDS", Integer, "Maximum time to allow any single file to run (default: #{file_timeout_seconds})") do |s|
+          self.file_timeout_seconds = s
+        end
+
+        parser.on("-P", "--pattern PATTERN", "A glob to use to select files to run (default: #{pattern})") do |pattern|
+          self.pattern = pattern
+        end
+
+        parser.on_tail("-h", "--help", "Prints this help") do
+          help_requested!
+        end
+      end
+    end
+
+    def extract_files_and_rspec_options(remaining_args)
+      files = []
+      rspec_options = []
+      target = files
+      remaining_args.each do |arg|
+        if arg[0] == '-'
+          target = rspec_options
+        end
+        target << arg
+      end
+
+      self.explicit_files_or_directories = files unless files.empty?
+      self.rspec_options = rspec_options unless rspec_options.empty?
+    end
+  end
+end

data/lib/rspec/multiprocess_runner/coordinator.rb

@@ -0,0 +1,197 @@
+# encoding: utf-8
+require 'rspec/multiprocess_runner'
+require 'rspec/multiprocess_runner/worker'
+
+module RSpec::MultiprocessRunner
+  class Coordinator
+    def initialize(worker_count, file_timeout, rspec_options, files)
+      @worker_count = worker_count
+      @file_timeout = file_timeout
+      @rspec_options = rspec_options
+      @spec_files = files
+      @workers = []
+      @deactivated_workers = []
+    end
+
+    def run
+      @start_time = Time.now
+      expected_worker_numbers.each do |n|
+        create_and_start_worker_if_necessary(n)
+      end
+      run_loop
+      quit_all_workers
+      print_summary
+
+      !failed?
+    end
+
+    def failed?
+      !@deactivated_workers.empty? || any_example_failed?
+    end
+
+    private
+
+    def worker_sockets
+      @workers.map(&:socket)
+    end
+
+    def run_loop
+      loop do
+        act_on_available_worker_messages(0.3)
+        reap_stalled_workers
+        start_missing_workers
+        break unless @workers.detect(&:working?)
+      end
+    end
+
+    def quit_all_workers
+      quit_threads = @workers.map do |worker|
+        Thread.new do
+          worker.quit
+          worker.wait_until_quit
+        end
+      end
+      quit_threads.each(&:join)
+    end
+
+    def work_left_to_do?
+      !@spec_files.empty?
+    end
+
+    def act_on_available_worker_messages(timeout)
+      while (select_result = IO.select(worker_sockets, nil, nil, timeout))
+        select_result.first.each do |readable_socket|
+          ready_worker = @workers.detect { |worker| worker.socket == readable_socket }
+          worker_status = ready_worker.receive_and_act_on_message_from_worker
+          if worker_status == :dead
+            reap_one_worker(ready_worker, "died")
+          elsif work_left_to_do? && !ready_worker.working?
+            ready_worker.run_file(@spec_files.shift)
+          end
+        end
+      end
+    end
+
+    def reap_one_worker(worker, reason)
+      worker.reap
+      @deactivated_workers << worker
+      worker.deactivation_reason = reason
+      @workers.reject! { |w| w == worker }
+    end
+
+    def reap_stalled_workers
+      @workers.select(&:stalled?).each do |stalled_worker|
+        reap_one_worker(stalled_worker, "stalled")
+      end
+    end
+
+    def expected_worker_numbers
+      (1..@worker_count).to_a
+    end
+
+    def create_and_start_worker_if_necessary(n)
+      if work_left_to_do?
+        $stderr.puts "(Re)starting worker #{n}"
+        new_worker = Worker.new(n, @file_timeout, @rspec_options)
+        @workers << new_worker
+        new_worker.start
+        new_worker.run_file(@spec_files.shift)
+      end
+    end
+
+    def start_missing_workers
+      if @workers.size < @worker_count && work_left_to_do?
+        running_process_numbers = @workers.map(&:environment_number)
+        missing_process_numbers = expected_worker_numbers - running_process_numbers
+        missing_process_numbers.each do |n|
+          create_and_start_worker_if_necessary(n)
+        end
+      end
+    end
+
+    def print_summary
+      elapsed = Time.now - @start_time
+      by_status_and_time = combine_example_results.each_with_object({}) do |result, idx|
+        (idx[result.status] ||= []) << result
+      end
+      print_pending_example_details(by_status_and_time["pending"])
+      print_failed_example_details(by_status_and_time["failed"])
+      print_failed_process_details
+      puts
+      print_elapsed_time(elapsed)
+      puts failed? ? "FAILURE" : "SUCCESS"
+      print_example_counts(by_status_and_time)
+    end
+
+    def combine_example_results
+      (@workers + @deactivated_workers).flat_map(&:example_results).sort_by { |r| r.time_finished }
+    end
+
+    def any_example_failed?
+      (@workers + @deactivated_workers).detect { |w| w.example_results.detect { |r| r.status == "failed" } }
+    end
+
+    def print_pending_example_details(pending_example_results)
+      return if pending_example_results.nil?
+      puts
+      puts "Pending:"
+      pending_example_results.each do |pending|
+        puts
+        puts pending.details.sub(/^\s*Pending:\s*/, '')
+      end
+    end
+
+    def print_failed_example_details(failed_example_results)
+      return if failed_example_results.nil?
+      puts
+      puts "Failures:"
+      failed_example_results.each_with_index do |failure, i|
+        puts
+        puts "  #{i.next}) #{failure.description}"
+        puts failure.details
+      end
+    end
+
+    # Copied from RSpec
+    def pluralize(count, string)
+      "#{count} #{string}#{'s' unless count.to_f == 1}"
+    end
+
+    def print_example_counts(by_status_and_time)
+      example_count = by_status_and_time.map { |status, results| results.size }.inject(0) { |sum, ct| sum + ct }
+      failure_count = by_status_and_time["failed"] ? by_status_and_time["failed"].size : 0
+      pending_count = by_status_and_time["pending"] ? by_status_and_time["pending"].size : 0
+      process_failure_count = @deactivated_workers.size
+
+      # Copied from RSpec
+      summary = pluralize(example_count, "example")
+      summary << ", " << pluralize(failure_count, "failure")
+      summary << ", #{pending_count} pending" if pending_count > 0
+      summary << ", " << pluralize(process_failure_count, "failed proc") if process_failure_count > 0
+      puts summary
+    end
+
+    def print_failed_process_details
+      return if @deactivated_workers.empty?
+      puts
+      puts "Failed processes:"
+      @deactivated_workers.each do |worker|
+        puts "  - #{worker.pid} (env #{worker.environment_number}) #{worker.deactivation_reason} on #{worker.current_file}"
+      end
+    end
+
+    def print_elapsed_time(seconds_elapsed)
+      minutes = seconds_elapsed.to_i / 60
+      seconds = seconds_elapsed % 60
+      m =
+        if minutes > 0
+          "%d minute%s" % [minutes, minutes == 1 ? '' : 's']
+        end
+      s =
+        if seconds > 0
+          "%.2f second%s" % [seconds, seconds == 1 ? '' : 's']
+        end
+      puts "Finished in #{[m, s].compact.join(", ")}"
+    end
+  end
+end

data/lib/rspec/multiprocess_runner/rake_task.rb

@@ -0,0 +1,114 @@
+require 'rspec/multiprocess_runner'
+require 'rake'
+require 'rake/tasklib'
+require 'shellwords'
+
+module RSpec::MultiprocessRunner
+  # Rake task to invoke `multispec`. Lots of it is copied from RSpec::Core::RakeTask.
+  #
+  # @see Rakefile
+  class RakeTask < ::Rake::TaskLib
+    include ::Rake::DSL if defined?(::Rake::DSL)
+
+    # Default path to the multirspec executable.
+    DEFAULT_MULTIRSPEC_PATH = File.expand_path('../../../../exe/multirspec', __FILE__)
+
+    # Name of task. Defaults to `:multispec`.
+    attr_accessor :name
+
+    # Files matching this pattern will be loaded.
+    # Defaults to `'**/*_spec.rb'`.
+    attr_accessor :pattern
+
+    # File search will be limited to these directories or specific files.
+    # Defaults to nil.
+    attr_accessor :files_or_directories
+    alias_method :files=, :files_or_directories=
+    alias_method :directories=, :files_or_directories=
+
+    # The number of workers to run. Defaults to 3.
+    attr_accessor :worker_count
+
+    # The maximum number of seconds to allow a single spec file to run
+    # before killing it. Defaults to 300.
+    attr_accessor :file_timeout_seconds
+
+    # Whether or not to fail Rake when an error occurs (typically when
+    # examples fail). Defaults to `true`.
+    attr_accessor :fail_on_error
+
+    # A message to print to stderr when there are failures.
+    attr_accessor :failure_message
+
+    # Use verbose output. If this is set to true, the task will print the
+    # executed spec command to stdout. Defaults to `true`.
+    attr_accessor :verbose
+
+    # Path to the multispec executable. Defaults to the absolute path to the
+    # rspec binary from the loaded rspec-core gem.
+    attr_accessor :multirspec_path
+
+    # Command line options to pass to the RSpec workers. Defaults to `nil`.
+    attr_accessor :rspec_opts
+
+    def initialize(*args, &task_block)
+      @name            = args.shift || :multispec
+      @verbose         = true
+      @fail_on_error   = true
+      @multirspec_path = DEFAULT_MULTIRSPEC_PATH
+
+      define(args, &task_block)
+    end
+
+    # @private
+    def run_task(verbose)
+      command = spec_command
+      puts Shellwords.shelljoin(command) if verbose
+
+      return if system(*command)
+      puts failure_message if failure_message
+
+      return unless fail_on_error
+      $stderr.puts "#{command} failed" if verbose
+      exit $?.exitstatus
+    end
+
+    private
+
+    # @private
+    def define(args, &task_block)
+      desc "Run RSpec code examples" unless ::Rake.application.last_comment
+
+      task name, *args do |_, task_args|
+        RakeFileUtils.__send__(:verbose, verbose) do
+          task_block.call(*[self, task_args].slice(0, task_block.arity)) if task_block
+          run_task verbose
+        end
+      end
+    end
+
+    def spec_command
+      cmd_parts = []
+      cmd_parts << RUBY
+      cmd_parts << multirspec_path
+      if worker_count
+        cmd_parts << '--worker-count' << worker_count.to_s
+      end
+      if file_timeout_seconds
+        cmd_parts << '--file-timeout' << file_timeout_seconds.to_s
+      end
+      if pattern
+        cmd_parts << '--pattern' << pattern
+      end
+      if files_or_directories
+        cmd_parts.concat(files_or_directories)
+      end
+      if rspec_opts
+        cmd_parts << '--'
+        cmd_parts.concat(Shellwords.shellsplit rspec_opts)
+      end
+
+      cmd_parts
+    end
+  end
+end

data/lib/rspec/multiprocess_runner/reporting_formatter.rb

@@ -0,0 +1,77 @@
+# encoding: utf-8
+require 'rspec/multiprocess_runner'
+require 'rspec/core/formatters/base_text_formatter'
+
+module RSpec::MultiprocessRunner
+  ##
+  # RSpec formatter used by workers to communicate spec execution to the
+  # coordinator.
+  #
+  # @private
+  class ReportingFormatter < RSpec::Core::Formatters::BaseTextFormatter
+    class << self
+      # The worker to which to report spec status. This has to be a class-level
+      # attribute because you can't access the formatter instance used by
+      # RSpec's runner.
+      attr_accessor :worker
+    end
+
+    def initialize(*ignored_args)
+      super(StringIO.new)
+      @current_example_groups = []
+    end
+
+    def example_group_started(example_group)
+      super(example_group)
+
+      @current_example_groups.push(example_group.description.strip)
+    end
+
+    def example_group_finished(example_group)
+      @current_example_groups.pop
+    end
+
+    def example_passed(example)
+      super(example)
+      report_example_result(:passed, current_example_description(example))
+    end
+
+    def example_pending(example)
+      super(example)
+      details = capture_output { dump_pending }
+      pending_examples.clear
+      report_example_result(:pending, current_example_description(example), details)
+    end
+
+    def example_failed(example)
+      super(example)
+      details = capture_output {
+        dump_failure_info(example)
+        dump_backtrace(example)
+      }
+      report_example_result(:failed, current_example_description(example), details)
+    end
+
+    private
+
+    def capture_output
+      output.string = ""
+      yield
+      captured = output.string
+      output.string = ""
+      captured
+    end
+
+    def worker
+      self.class.worker
+    end
+
+    def current_example_description(example)
+      (@current_example_groups + [example.description.strip]).join('·')
+    end
+
+    def report_example_result(example_status, description, details=nil)
+      worker.report_example_result(example_status, description, details)
+    end
+  end
+end

data/lib/rspec/multiprocess_runner/version.rb

@@ -0,0 +1,5 @@
+module RSpec
+  module MultiprocessRunner
+    VERSION = "0.1.0"
+  end
+end

data/lib/rspec/multiprocess_runner/worker.rb

@@ -0,0 +1,262 @@
+# encoding: utf-8
+require "rspec/multiprocess_runner"
+require "rspec/multiprocess_runner/reporting_formatter"
+
+require "rspec/core"
+require "rspec/core/runner"
+
+require "socket"
+require "json"
+require "timeout"
+
+module RSpec::MultiprocessRunner
+  ##
+  # This object has several roles:
+  # - It forks the worker process
+  # - In the coordinator process, it is used to send messages to the worker and
+  #   track the worker's status, completed specs, and example results.
+  # - In the worker process, it is used to send messages to the coordinator and
+  #   actually run specs.
+  #
+  # @private
+  class Worker
+    attr_reader :pid, :environment_number, :example_results, :current_file
+    attr_accessor :deactivation_reason
+
+    COMMAND_QUIT = "quit"
+    COMMAND_RUN_FILE = "run_file"
+
+    STATUS_EXAMPLE_COMPLETE = "example_complete"
+    STATUS_RUN_COMPLETE = "run_complete"
+
+    def initialize(environment_number, file_timeout, rspec_arguments=[])
+      @environment_number = environment_number
+      @worker_socket, @coordinator_socket = Socket.pair(:UNIX, :STREAM)
+      @rspec_arguments = rspec_arguments + ["--format", ReportingFormatter.to_s]
+      @file_timeout = file_timeout
+      @example_results = []
+
+      # Use a single configuration and world across all individual runs
+      # This will not be necessary to do manually in RSpec 3 — it does not
+      # reset the globals after each run.
+      @rspec_configuration = RSpec.configuration
+      @rspec_world = RSpec.world
+    end
+
+    ##
+    # Workers can be found in the coordinator process by their coordinator socket.
+    def ==(other)
+      case other
+      when Socket
+        other == @coordinator_socket
+      else
+        super
+      end
+    end
+
+    ##
+    # Forks the worker process. In the parent, returns the PID.
+    def start
+      pid = fork
+      if pid
+        @worker_socket.close
+        @pid = pid
+      else
+        @coordinator_socket.close
+        @pid = Process.pid
+        ENV["TEST_ENV_NUMBER"] = environment_number.to_s
+        set_process_name
+        run_loop
+      end
+    end
+
+    def socket
+      if self.pid == Process.pid
+        @worker_socket
+      else
+        @coordinator_socket
+      end
+    end
+
+    ###### COORDINATOR METHODS
+    ## These are methods that the coordinator process calls on its copy of
+    ## the workers.
+
+    public
+
+    def quit
+      send_message_to_worker(command: COMMAND_QUIT)
+    end
+
+    def wait_until_quit
+      Process.wait(self.pid)
+    end
+
+    def run_file(filename)
+      send_message_to_worker(command: COMMAND_RUN_FILE, filename: filename)
+      @current_file = filename
+      @current_file_started_at = Time.now
+    end
+
+    def working?
+      @current_file
+    end
+
+    def stalled?
+      working? && (Time.now - @current_file_started_at > @file_timeout)
+    end
+
+    def reap
+      begin
+        Timeout.timeout(4) do
+          $stderr.puts "Reaping troubled process #{environment_number} (#{pid}; #{@current_file}) with QUIT"
+          Process.kill(:QUIT, pid)
+          Process.wait(pid)
+        end
+      rescue Timeout::Error
+        $stderr.puts "Reaping troubled process #{environment_number} (#{pid}) with KILL"
+        Process.kill(:KILL, pid)
+        Process.wait(pid)
+      end
+    end
+
+    def receive_and_act_on_message_from_worker
+      act_on_message_from_worker(receive_message_from_worker)
+    end
+
+    private
+
+    def receive_message_from_worker
+      receive_message(@coordinator_socket)
+    end
+
+    def act_on_message_from_worker(message_hash)
+      return :dead unless message_hash # ignore EOF
+      case message_hash["status"]
+      when STATUS_RUN_COMPLETE
+        @current_file = nil
+        @current_file_started_at = nil
+      when STATUS_EXAMPLE_COMPLETE
+        example_results << ExampleResult.new(message_hash)
+        suffix =
+          case message_hash["example_status"]
+          when "failed"
+            " - FAILED"
+          when "pending"
+            " - pending"
+          end
+        if message_hash["details"]
+          suffix += "\n#{message_hash["details"]}"
+        end
+        $stdout.puts "#{environment_number} (#{pid}): #{message_hash["description"]}#{suffix}"
+      else
+        $stderr.puts "Received unsupported status #{message_hash["status"].inspect} in worker #{pid}"
+      end
+      return :alive
+    end
+
+    def send_message_to_worker(message_hash)
+      send_message(@coordinator_socket, message_hash)
+    end
+
+    ###### WORKER METHODS
+    ## These are methods that the worker process calls on the copy of this
+    ## object that lives in the fork.
+
+    public
+
+    def report_example_result(example_status, description, details)
+      send_message_to_coordinator(
+        status: STATUS_EXAMPLE_COMPLETE,
+        example_status: example_status,
+        description: description,
+        details: details
+      )
+    end
+
+    private
+
+    def set_process_name
+      name = "RSpec::MultiprocessRunner::Worker #{environment_number}"
+      status = current_file ? "running #{current_file}" : "idle"
+      $0 = "#{name} #{status}"
+    end
+
+    def run_loop
+      loop do
+        select_result = IO.select([@worker_socket], nil, nil, 1)
+        if select_result
+          readables, _, _ = select_result
+          act_on_message_from_coordinator(
+            receive_message_from_coordinator(readables.first)
+          )
+        end
+      end
+    end
+
+    def receive_message_from_coordinator(socket)
+      receive_message(socket)
+    end
+
+    def send_message_to_coordinator(message_hash)
+      send_message(@worker_socket, message_hash)
+    end
+
+    def act_on_message_from_coordinator(message_hash)
+      return unless message_hash # ignore EOF
+      case message_hash["command"]
+      when "quit"
+        exit
+      when "run_file"
+        execute_spec(message_hash["filename"])
+      else
+        $stderr.puts "Received unsupported command #{message_hash["command"].inspect} in worker #{pid}"
+      end
+      set_process_name
+    end
+
+    def execute_spec(spec_file)
+      @current_file = spec_file
+      set_process_name
+
+      RSpec.configuration = @rspec_configuration
+      RSpec.world = @rspec_world
+      # If we don't do this, every previous spec is run every time run is called
+      RSpec.world.example_groups.clear
+
+      ReportingFormatter.worker = self
+      RSpec::Core::Runner.run(@rspec_arguments + [spec_file])
+      send_message_to_coordinator(status: STATUS_RUN_COMPLETE, filename: spec_file)
+    ensure
+      @current_file = nil
+    end
+
+    ###### UTILITY FUNCTIONS
+    ## Methods that used by both the coordinator and worker processes.
+
+    private
+
+    def receive_message(socket)
+      message_json = socket.gets
+      if message_json
+        JSON.parse(message_json)
+      end
+    end
+
+    def send_message(socket, message_hash)
+      socket.puts(message_hash.to_json)
+    end
+  end
+
+  # @private
+  class ExampleResult
+    attr_reader :status, :description, :details, :time_finished
+
+    def initialize(example_complete_message)
+      @status = example_complete_message["example_status"]
+      @description = example_complete_message["description"]
+      @details = example_complete_message["details"]
+      @time_finished = Time.now
+    end
+  end
+end

data/lib/rspec/multiprocess_runner.rb

@@ -0,0 +1,6 @@
+require "rspec/multiprocess_runner/version"
+
+module RSpec
+  module MultiprocessRunner
+  end
+end

data/rspec-multiprocess_runner.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rspec/multiprocess_runner/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rspec-multiprocess_runner"
+  spec.version       = RSpec::MultiprocessRunner::VERSION
+  spec.authors       = ["Rhett Sutphin"]
+  spec.email         = ["rhett@detailedbalance.net"]
+
+  spec.summary       = %q{A runner for RSpec 2 that uses multiple processes to execute specs in parallel}
+  spec.homepage      = "https://github.com/cdd/rspec-multiprocess_runner"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|manual_test_specs)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rspec-core", "~> 2.0", "< 2.99.0"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: rspec-multiprocess_runner
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Rhett Sutphin
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-12-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - <
+      - !ruby/object:Gem::Version
+        version: 2.99.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - <
+      - !ruby/object:Gem::Version
+        version: 2.99.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- rhett@detailedbalance.net
+executables:
+- multirspec
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODO.md
+- bin/console
+- bin/setup
+- exe/multirspec
+- lib/rspec/multiprocess_runner.rb
+- lib/rspec/multiprocess_runner/command_line_options.rb
+- lib/rspec/multiprocess_runner/coordinator.rb
+- lib/rspec/multiprocess_runner/rake_task.rb
+- lib/rspec/multiprocess_runner/reporting_formatter.rb
+- lib/rspec/multiprocess_runner/version.rb
+- lib/rspec/multiprocess_runner/worker.rb
+- rspec-multiprocess_runner.gemspec
+homepage: https://github.com/cdd/rspec-multiprocess_runner
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1609184745420465239
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1609184745420465239
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: A runner for RSpec 2 that uses multiple processes to execute specs in parallel
+test_files: []