xpool 0.3.0 → 0.9.0

data/.pryrc

@@ -0,0 +1 @@
+require "./lib/xpool"

data/.travis.yml

@@ -0,0 +1,8 @@
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - ruby-head
+
+notifications:
+  email: true 

data/ChangeLog.txt

@@ -1,3 +1,60 @@
+== v0.9.0
+	- upgrade to ichannel v5.1.1
+	Which in turn fixes a performance bug in XPool#schedule. With ichannel v5.0.1 
+	the suite runs in 23~ seconds, but with v5.1.1 we run the suite in 3~ seconds.
+	I don't think the performance hit was that bad in earlier versions, but given
+	the right set of circumstances I'm sure it would be an issue.
+
+	- add XPool::Process#idle?
+	Returns true when the subprocess is considered idle. "idle" means the
+	subprocess is not executing a unit of work.
+
+	- conserve CPU consumption by sleeping for a short period of time.
+	By sleeping for a short period of time we avoid pegging the CPU at 
+	80-100% when a subprocess is idle.
+
+	- add XPool::Process#backtrace
+	Returns the backtrace of the exception that caused a subprocess to fail. Returns 
+	nil whenever the subprocess is not in a failed state.
+
+	- add XPool::Process#failed?
+	Returns true when a unit of work does not handle an exception, which causes
+	the subprocess it is running in to exit. A failed subprocess can be restarted
+	through Process#restart.
+
+	- add XPool::Process#restart
+	Restarts a subprocess by gracefully shutting down and respawning a new subprocess.
+
+	- add XPool#dry?
+	Returns true when all subprocesses in the pool are busy.
+
+	- XPool::Process#schedule raises when the subprocess is dead
+	Incase the subprocess has been shutdown a call to XPool::Process#schedule will
+	raise a RuntimeError.
+
+	- XPool#schedule raises when the pool has no active subprocesses
+	Incase the pool has been shutdown a call to XPool#schedule will raise a 
+	RuntimeError.
+
+	- add XPool::Process#frequency
+	Returns the number of times a subprocess has been asked to schedule work.
+		
+	- XPool#schedule schedules work on the least busy subprocess
+	The subprocess picked to run a unit of work is the one who is least busy. 
+	"least busy" means it has been asked to schedule the least amount of 
+	work.
+
+	- XPool#schedule returns a XPool::Process object.
+	The subprocess that has been picked to run your unit of work is returned 
+	by schedule in case you want to interact with the subprocess later on.
+
+	- Add XPool#broadcast
+	The broadcast method can distribute one unit of work across all 
+	subprocesses in the pool.
+
+	- Add XPool::Process#busy?
+	Returns true when the subprocess is executing a unit of work.	
+
 == v0.3.0
 	* Add XPool#size.
 	It returns the number of alive subprocesses in the pool.

data/Gemfile

@@ -1,6 +1,7 @@
 source 'http://rubygems.org'
 group :development do
   gem 'rake'
-  gem 'ichannel', path: '../ichannel' if File.exists? '../ichannel'
+  gem 'pry'
+  gem 'ruby-prof'
 end
 gemspec

data/README.md

@@ -1,31 +1,49 @@
 __OVERVIEW__
 
-| Project         | XPool
+| Project         | xpool
 |:----------------|:--------------------------------------------------
 | Homepage        | https://github.com/robgleeson/xpool
-| Documentation   | http://rubydoc.info/gems/xpool/frames 
-| CI              | [![Build Status](https://travis-ci.org/robgleeson/xpool.png)](https://travis-ci.org/robgleeson/XPool)
+| Documentation   | http://rubydoc.info/github/robgleeson/xpool/frames 
+| CI              | [![Build Status](https://travis-ci.org/robgleeson/xpool.png)](https://travis-ci.org/robgleeson/xpool)
 | Author          | Rob Gleeson             
 
 
 __DESCRIPTION__
 
-A lightweight UNIX(X) Process Pool written in Ruby. The size of the pool
-is dynamic and it can be resized at runtime if needs be. 'Units of work' are
-what you can schedule and each unit of work is dispatched by a free subprocess 
-in the the pool. If the pool dries up(all subprocesses are busy) the units 
-of work are queued & the next available subprocess will pick it up.
+xpool is a lightweight process pool. The pool manages a group of subprocesses
+that are used when the pool is asked to dispatch a 'unit of work'. A 
+'unit of work' is defined as any object that implements the `run` method.
 
-There are also all the other features you might expect, such as an interface to 
-shutdown gracefully or to shutdown immediately. Graceful shutdowns can operate 
-within a timeout that when passed shuts down the pool immediately. 
+All subprocesses in the pool have their own message queue that the pool places
+work onto according to a very simple algorithm: the subprocess who has scheduled
+the least amount of work is the subprocess who is asked to put the work on its
+queue. The message queue that each subprocess has is also  what ensures work 
+can be queued when the pool becomes dry (all subprocesses are busy). 
 
+Incase a unit of work raises an exception that it does not handle xpool will
+catch the exception and mark the process as 'failed'. A failed process can be
+restarted, and it is also possible to access the backtrace of a failed process 
+through `XPool` and `XPool::Process` objects. The exception is also re-raised 
+so that you can see a process has failed from the output ruby prints when an 
+exception is left unhandled.
+
+__POOL SIZE__
+
+By default xpool will create a pool with X subprocesses, where X is the number 
+of cores on your CPU. This seems like a reasonable default, but if you should 
+decide to choose otherwise you can set the size of the pool when it is 
+initialized. The pool can also be resized at runtime if you decide you need to 
+scale up or down.
 
 __EXAMPLES__
 
+The examples don't demonstrate everything that xpool can do. The 
+[API docs](http://rubydoc.info/github/robgleeson/xpool) 
+cover the missing pieces.
+
 _1._
 
-A demo of how you'd create a pool of 5 subprocesses:
+A demo of how to schedule a unit of work: 
 
 ```ruby
 #
@@ -38,44 +56,47 @@ class Unit
     sleep 1
   end
 end
-pool = XPool.new 5
-5.times { pool.schedule Unit.new }
+pool = XPool.new 2
+pool.schedule Unit.new
 pool.shutdown
 ```
 
 _2._
 
-A demo of how you'd resize the pool from 10 to 5 subprocesses at runtime:
+A demo of how you can interact with subprocesses through 
+[XPool::Process](http://rdoc.info/github/robgleeson/xpool/master/XPool/Process)
+objects:
 
 ```ruby
 class Unit
   def run
-    sleep 5
+    sleep 1
   end
 end
-pool = XPool.new 10
-pool.resize! 1..5
-pool.shutdown
+pool = XPool.new 2
+subprocess = pool.schedule Unit.new 
+p subprocess.busy? # => true
 ```
+
 _3._
 
-A demo of how you'd gracefully shutdown but force a hard shutdown if 3 seconds
-pass by & all subprocesses have not exited:
+A demo of how to run a single unit of work across all subprocesses in the
+pool:
 
 ```ruby
 class Unit
   def run
-    sleep 5
+    puts Process.pid
   end
 end
-pool = XPool.new 5
-pool.schedule Unit.new
-pool.shutdown 3
+pool = XPool.new 4
+pool.broadcast Unit.new
+pool.shutdown
 ```
 
 __DEBUGGING OUTPUT__
 
-XPool can print helpful debugging information if you set `XPool.debug` 
+xpool can print helpful debugging information if you set `XPool.debug` 
 to true:
 
 ```ruby
@@ -86,7 +107,7 @@ Or you can temporarily enable debugging output for the duration of a block:
 
 ```ruby
 XPool.debug do 
-  pool = XPool.new 5
+  pool = XPool.new 2
   pool.shutdown
 end
 ```
@@ -94,6 +115,14 @@ end
 The debugging information you'll see is all about how the pool is operating. 
 It can be interesting to look over even if you're not bug hunting.
 
+__SIGUSR1__
+
+All xpool managed subprocesses define a signal handler for the SIGUSR1 signal.
+A unit of work should never define a signal handler for SIGUSR1 because that 
+would overwrite the handler defined by xpool. SIGUSR2 is not caught by xpool
+and it could be a good second option.
+
+
 __INSTALL__
 
     $ gem install xpool

data/bench/pool-schedule.rb

@@ -0,0 +1,15 @@
+require "xpool"
+require "ruby-prof"
+class Unit
+  def run(x = 1)
+    sleep x
+  end
+end
+
+pool = XPool.new 5
+result = RubyProf.profile do
+  5.times { pool.schedule Unit.new }
+end
+pool.shutdown
+printer = RubyProf::FlatPrinter.new(result)
+printer.print

data/lib/xpool/process.rb

@@ -1,10 +1,10 @@
 class XPool::Process
   #
-  # @param [Fixnum] id
-  #   The Process ID.
+  # @return [XPool::Process]
+  #   Returns an instance of XPool::Process
   #
-  def initialize(id)
-    @id = id
+  def initialize
+    @id = spawn
   end
 
   #
@@ -17,7 +17,7 @@ class XPool::Process
   # @return [void]
   #
   def shutdown
-    _shutdown 'SIGUSR1'
+    _shutdown 'SIGUSR1' unless @shutdown
   end
 
   #
@@ -26,7 +26,65 @@ class XPool::Process
   # @return [void]
   #
   def shutdown!
-    _shutdown 'SIGKILL'
+    _shutdown 'SIGKILL' unless @shutdown
+  end
+
+  #
+  # @return [Fixnum]
+  #   The number of times the process has been asked to schedule work.
+  #
+  def frequency
+    @frequency
+  end
+
+  #
+  # @param [#run] unit
+  #   The unit of work
+  #
+  # @param [Object] *args
+  #   A variable number of arguments to be passed to #run
+  #
+  # @raise [RuntimeError]
+  #   When the process is dead.
+  #
+  # @return [XPool::Process]
+  #   Returns self
+  #
+  def schedule(unit,*args)
+    if dead?
+      raise RuntimeError,
+        "cannot schedule work on a dead process (with ID: #{@id})"
+    end
+    @frequency += 1
+    @channel.put unit: unit, args: args
+    self
+  end
+
+  #
+  # @return [Boolean]
+  #   Returns true when the process is executing work.
+  #
+  def busy?
+    synchronize!
+    @states[:busy]
+  end
+
+  #
+  # @return [Boolean]
+  #   Returns true when the process is not executing a unit of work.
+  #
+  def idle?
+    !busy?
+  end
+
+  #
+  # @return [Boolean]
+  #   Returns true when a subprocess has failed due to an unhandled
+  #   exception.
+  #
+  def failed?
+    synchronize!
+    @states[:failed]
   end
 
   #
@@ -42,17 +100,86 @@ class XPool::Process
   #   Returns true when the process is no longer running.
   #
   def dead?
-    @dead
+    synchronize!
+    @states[:dead]
+  end
+
+  #
+  # If a process has failed (see #failed?) this method returns the backtrace of
+  # the exception that caused the process to fail.
+  #
+  # @return [Array<String>]
+  #   Returns the backtrace.
+  #
+  def backtrace
+    synchronize!
+    @states[:backtrace]
+  end
+
+  #
+  # @return [Fixnum]
+  #   Returns the process ID of the new process.
+  #
+  def restart
+    shutdown
+    @id = spawn
   end
 
 private
   def _shutdown(sig)
-    begin
-      Process.kill sig, @id
-      Process.wait @id
-    rescue SystemCallError
-    ensure
-      @dead = true
+    Process.kill sig, @id
+    Process.wait @id
+  rescue Errno::ECHILD, Errno::ESRCH
+  ensure
+    @states = {dead: true}
+    @shutdown = true
+    @channel.close
+    @s_channel.close
+  end
+
+  def synchronize!
+    return if @shutdown
+    while @s_channel.readable?
+      @states = @s_channel.get
+    end
+    @states
+  end
+
+  def reset
+    @channel = IChannel.new Marshal
+    @s_channel = IChannel.new Marshal
+    @shutdown = false
+    @states = {}
+    @frequency = 0
+  end
+
+  def spawn
+    reset
+    fork do
+      trap :SIGUSR1 do
+        XPool.log "#{::Process.pid} got request to shutdown."
+        @shutdown_requested = true
+      end
+      loop &method(:read_loop)
+    end
+  end
+
+  def read_loop
+    if @channel.readable?
+      @s_channel.put busy: true
+      msg = @channel.get
+      msg[:unit].run *msg[:args]
+      @s_channel.put busy: false
+    end
+    sleep 0.05
+  rescue Exception => e
+    XPool.log "#{::Process.pid} has failed."
+    @s_channel.put failed: true, dead: true, backtrace: e.backtrace
+    raise e
+  ensure
+    if @shutdown_requested && !@channel.readable?
+      XPool.log "#{::Process.pid} is about to exit."
+      exit 0
     end
   end
 end

data/lib/xpool/version.rb

@@ -1,3 +1,3 @@
 class XPool
-  VERSION = "0.3.0"
+  VERSION = "0.9.0"
 end

data/lib/xpool.rb

@@ -37,9 +37,33 @@ class XPool
   # @return [XPool]
   #
   def initialize(size=number_of_cpu_cores)
-    @channel = IChannel.new Marshal
-    @pool = Array.new size do
-      spawn
+    @pool = Array.new(size) { Process.new }
+  end
+
+  #
+  # @return [Array<XPool::Process>]
+  #   Returns an Array of failed processes.
+  #
+  def failed_processes
+    @pool.select(&:failed?)
+  end
+
+  #
+  # Broadcasts _unit_ to be run across all subprocesses in the pool.
+  #
+  # @example
+  #   pool = XPool.new 5
+  #   pool.broadcast unit
+  #
+  # @raise [RuntimeError]
+  #   When a subprocess in the pool is dead.
+  #
+  # @return [Array<XPool::Process>]
+  #   Returns an array of XPool::Process objects
+  #
+  def broadcast(unit, *args)
+    @pool.map do |process|
+      process.schedule unit, *args
     end
   end
 
@@ -98,9 +122,7 @@ class XPool
   #
   def resize!(range)
     shutdown!
-    @pool = range.to_a.map do
-      spawn
-    end
+    @pool = range.to_a.map { Process.new }
   end
 
   #
@@ -109,11 +131,19 @@ class XPool
   # @param
   #   (see Process#schedule)
   #
-  # @return
-  #   (see Process#schedule)
+  # @raise [RuntimeError]
+  #   When the pool is dead (no subprocesses are left running)
   #
-  def schedule(unit, *args)
-    @channel.put unit: unit, args: args
+  # @return [XPool::Process]
+  #   Returns an instance of XPool::Process.
+  #
+  def schedule(unit,*args)
+    if size == 0 # dead pool
+      raise RuntimeError,
+        "cannot schedule unit of work on a dead pool"
+    end
+    process = @pool.reject(&:dead?).min_by { |p| p.frequency }
+    process.schedule unit, *args
   end
 
   #
@@ -126,35 +156,12 @@ class XPool
     end
   end
 
-private
-  def spawn
-    pid = fork do
-      trap :SIGUSR1 do
-        XPool.log "#{::Process.pid} got request to shutdown."
-        @shutdown_requested = true
-      end
-      loop do
-        begin
-          #
-          # I've noticed that select can wait an infinite amount of time for
-          # a UNIXSocket to become readable. It usually happens on the tenth or
-          # so iteration. By checking if we have data to read first we elimate
-          # this problem but it is a band aid for a bigger issue I don't
-          # understand right now.
-          #
-          if @channel.readable?
-            msg = @channel.get
-            msg[:unit].run *msg[:args]
-          end
-        ensure
-          if @shutdown_requested && !@channel.readable?
-            XPool.log "#{::Process.pid} is about to exit."
-            break
-          end
-        end
-      end
-    end
-    Process.new pid
+  #
+  # @return [Boolean]
+  #   Returns true when all subprocesses in the pool are busy.
+  #
+  def dry?
+    @pool.all?(&:busy?)
   end
 
   #

data/test/setup.rb

@@ -2,4 +2,7 @@ require 'bundler/setup'
 require 'xpool'
 require 'test/unit'
 require 'fileutils'
+require_relative 'support/sleeper'
+require_relative 'support/io_writer'
+require_relative 'support/raiser'
 XPool.debug = ENV.has_key? "DEBUG"

data/test/support/io_writer.rb

@@ -0,0 +1,22 @@
+require 'tempfile'
+class IOWriter
+  def initialize
+    file = Tempfile.new '__xpool_test'
+    @path = file.path
+    file.close false
+  end
+
+  def run
+    File.open @path, 'w' do |f|
+      f.write 'true'
+      sleep 0.1
+    end
+  end
+
+  def run?
+    return @run if defined?(@run)
+    @run = File.read(@path) == 'true'
+    FileUtils.rm_rf @path
+    @run
+  end
+end

data/test/support/raiser.rb

@@ -0,0 +1,5 @@
+class Raiser
+  def run
+    raise RuntimeError, "", %w(42)
+  end
+end

data/test/support/sleeper.rb

@@ -0,0 +1,9 @@
+class Sleeper
+  def initialize(seconds)
+    @seconds = seconds
+  end
+
+  def run
+    sleep @seconds
+  end
+end

data/test/xpool_process_test.rb

@@ -0,0 +1,82 @@
+require_relative 'setup'
+class XPoolProcessTest < Test::Unit::TestCase
+  def setup
+    @process = XPool::Process.new
+  end
+
+  def teardown
+    @process.shutdown!
+  end
+
+  def test_busy_method
+    @process.schedule Sleeper.new(0.5)
+    sleep 0.1
+    assert @process.busy?, 'Expected process to be busy'
+    sleep 0.5
+    refute @process.busy?, 'Expected process to not be busy'
+  end
+
+  def test_busy_on_exception
+    @process.schedule Raiser.new
+    sleep 0.1
+    refute @process.busy?
+  end
+
+  def test_busy_method_on_dead_process
+    @process.schedule Sleeper.new(1)
+    @process.shutdown!
+    refute @process.busy?
+  end
+
+  def test_frequency
+    4.times { @process.schedule Sleeper.new(0.1) }
+    assert_equal 4, @process.frequency
+  end
+
+  def test_queue
+    unit1 = IOWriter.new
+    unit2 = IOWriter.new
+    @process.schedule unit1
+    @process.schedule unit2
+    @process.shutdown
+    assert unit1.run?
+    assert unit2.run?
+  end
+
+  def test_failed_on_failed_process
+    @process.schedule Raiser.new
+    sleep 0.1
+    assert @process.failed?
+  end
+
+  def test_restart_on_failed_process
+    @process.schedule Raiser.new
+    assert_instance_of Fixnum, @process.restart
+  end
+
+  def test_failed_process_is_also_dead
+    @process.schedule Raiser.new
+    sleep 0.1
+    assert @process.dead?
+  end
+
+  def test_backtrace
+    @process.schedule Raiser.new
+    sleep 0.1
+    assert_equal %w(42), @process.backtrace
+  end
+
+  def test_race_condition_in_process_forced_to_shutdown
+    @process.schedule IOWriter.new
+    sleep 0.5
+    @process.shutdown!
+    assert @process.dead?
+  end
+
+  def test_race_condition_in_process_shutdown_gracefully
+    @process.schedule IOWriter.new
+    sleep 0.5
+    @process.shutdown
+    assert @process.dead?
+  end
+end

data/test/xpool_test.rb

@@ -1,40 +1,17 @@
 require_relative 'setup'
 class XPoolTest < Test::Unit::TestCase
-  class Unit
-    def run
-      sleep 1
-    end
-  end
-
-  class XUnit
-    def initialize
-      file = Tempfile.new '__xpool_test'
-      @path = file.path
-      file.close false
-    end
-
-    def run
-      File.open @path, 'w' do |f|
-        f.write 'true'
-      end
-    end
-
-    def run?
-      return @run if defined?(@run)
-      @run = File.read(@path) == 'true'
-      FileUtils.rm_rf @path
-      @run
-    end
-  end
-
   def setup
     @pool = XPool.new 5
   end
 
   def teardown
-    @pool.shutdown
+    @pool.shutdown!
   end
 
+  def test_broadcast
+    subprocesses = @pool.broadcast Sleeper.new(1)
+    subprocesses.each { |subprocess| assert_equal 1, subprocess.frequency }
+  end
 
   def test_size_with_graceful_shutdown
     assert_equal 5, @pool.size
@@ -50,29 +27,32 @@ class XPoolTest < Test::Unit::TestCase
 
   def test_queue
     @pool.resize! 1..1
-    units = Array.new(5) { XUnit.new }
-    units.each do |unit|
-      @pool.schedule unit
-    end
-    @pool.shutdown
-    units.each do |unit|
-      assert unit.run?
-    end
+    subprocesses = Array.new(5) { @pool.schedule Sleeper.new(0.1) }.uniq!
+    assert_equal 1, subprocesses.size
+    assert_equal 5, subprocesses[0].frequency
   end
 
-  def test_parallelism
-    5.times do
-      @pool.schedule Unit.new
-    end
-    assert_nothing_raised Timeout::Error do
-      Timeout.timeout 2 do
-        @pool.shutdown
-      end
-    end
+  def test_distribution_of_work
+    subprocesses = (0..4).map { @pool.schedule Sleeper.new(0.1) }
+    subprocesses.each { |subprocess| assert_equal 1, subprocess.frequency }
   end
 
   def test_resize!
     @pool.resize! 1..1
     assert_equal 1, @pool.instance_variable_get(:@pool).size
   end
+
+  def test_dry?
+    refute @pool.dry?
+    5.times { @pool.schedule Sleeper.new(0.5) }
+    sleep 0.1
+    assert @pool.dry?
+  end
+
+  def test_failed_processes
+    @pool.schedule Raiser.new
+    sleep 0.1
+    assert_equal 1, @pool.failed_processes.size
+    assert_equal 4, @pool.size
+  end
 end

data/xpool.gemspec

@@ -14,5 +14,5 @@ Gem::Specification.new do |gem|
   gem.name          = "xpool"
   gem.require_paths = ["lib"]
   gem.version       = XPool::VERSION
-  gem.add_runtime_dependency 'ichannel', '~> 5.0.1'
+  gem.add_runtime_dependency 'ichannel', '~> 5.1.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xpool
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.9.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-29 00:00:00.000000000 Z
+date: 2013-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ichannel
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 5.0.1
+        version: 5.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 5.0.1
+        version: 5.1.1
 description: A lightweight UNIX(X) Process Pool implementation
 email:
 - rob@flowof.info
@@ -35,15 +35,23 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .pryrc
+- .travis.yml
 - ChangeLog.txt
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- bench/.gitkeep
+- bench/pool-schedule.rb
 - lib/xpool.rb
 - lib/xpool/process.rb
 - lib/xpool/version.rb
 - test/setup.rb
+- test/support/io_writer.rb
+- test/support/raiser.rb
+- test/support/sleeper.rb
+- test/xpool_process_test.rb
 - test/xpool_test.rb
 - xpool.gemspec
 homepage: ''
@@ -60,7 +68,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2000550100409961336
+      hash: -372428872314676490
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -69,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2000550100409961336
+      hash: -372428872314676490
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -78,4 +86,8 @@ specification_version: 3
 summary: A lightweight UNIX(X) Process Pool implementation
 test_files:
 - test/setup.rb
+- test/support/io_writer.rb
+- test/support/raiser.rb
+- test/support/sleeper.rb
+- test/xpool_process_test.rb
 - test/xpool_test.rb