xpool 0.1.1 → 0.3.0

data/ChangeLog.txt

@@ -0,0 +1,7 @@
+== v0.3.0
+	* Add XPool#size.
+	It returns the number of alive subprocesses in the pool.
+
+== v0.2.0
+	* Minor README & API documentation improvements.
+	* Change the default number of subprocesses to spawn in a pool from 10 to 5.

data/README.md

@@ -4,17 +4,17 @@ __OVERVIEW__
 |:----------------|:--------------------------------------------------
 | 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)
+| 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 implementation. The size of the pool
+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 they are dispatched by a subprocess in the pool. If 
-the pool dries up(all processes are busy) the units of work are queued & the 
-next available subprocess will pick it up.
+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.
 
 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 
@@ -25,7 +25,7 @@ __EXAMPLES__
 
 _1._
 
-A demo of how you'd create a pool of 10 subprocesses:
+A demo of how you'd create a pool of 5 subprocesses:
 
 ```ruby
 #
@@ -38,7 +38,7 @@ class Unit
     sleep 1
   end
 end
-pool = XPool.new 10
+pool = XPool.new 5
 5.times { pool.schedule Unit.new }
 pool.shutdown
 ```
@@ -68,11 +68,32 @@ class Unit
     sleep 5
   end
 end
-pool = XPool.new 10
+pool = XPool.new 5
 pool.schedule Unit.new
 pool.shutdown 3
 ```
 
+__DEBUGGING OUTPUT__
+
+XPool can print helpful debugging information if you set `XPool.debug` 
+to true:
+
+```ruby
+XPool.debug = true
+```
+
+Or you can temporarily enable debugging output for the duration of a block:
+
+```ruby
+XPool.debug do 
+  pool = XPool.new 5
+  pool.shutdown
+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.
+
 __INSTALL__
 
     $ gem install xpool

data/lib/xpool.rb

@@ -1,8 +1,8 @@
 class XPool
-  require 'json'
   require 'ichannel'
   require 'timeout'
   require 'logger'
+  require 'rbconfig'
   require_relative "xpool/version"
   require_relative "xpool/process"
 
@@ -23,7 +23,7 @@ class XPool
     @debug = boolean
   end
 
-  def self.log(msg, type = :info) 
+  def self.log(msg, type = :info)
     @logger = @logger || Logger.new(STDOUT)
     if @debug
       @logger.public_send type, msg
@@ -36,9 +36,9 @@ class XPool
   #
   # @return [XPool]
   #
-  def initialize(size=10)
+  def initialize(size=number_of_cpu_cores)
     @channel = IChannel.new Marshal
-    @pool = Array.new size do 
+    @pool = Array.new size do
       spawn
     end
   end
@@ -46,24 +46,22 @@ class XPool
   #
   # A graceful shutdown of the pool.
   #
-  # All busy subprocesses finish up any code they're running & exit normally 
+  # All busy subprocesses finish up any code they're running & exit normally
   # afterwards.
   #
-  # @param [Fixnum] timeout 
+  # @param [Fixnum] timeout
   #   An optional amount of seconds to wait before forcing a shutdown through
   #   {#shutdown!}.
   #
   # @see XPool::Process#spawn
-  # 
+  #
   # @return [void]
   #
   def shutdown(timeout=nil)
     if timeout
       begin
         Timeout.timeout(timeout) do
-          @pool.each do |process|
-            process.shutdown
-          end
+          @pool.each(&:shutdown)
         end
       rescue Timeout::Error
         XPool.log "'#{timeout}' seconds elapsed, switching to hard shutdown."
@@ -85,12 +83,12 @@ class XPool
 
   #
   # Resize the pool.
-  # All subprocesses in the pool are abruptly stopped through {#shutdown!} and 
+  # All subprocesses in the pool are abruptly stopped through {#shutdown!} and
   # a new pool the size of _range_ is created.
   #
   # @example
-  #   pool = XPool.new 10
-  #   pool.resiz!e 1..5 
+  #   pool = XPool.new 5
+  #   pool.resize! 1..3
   #   pool.shutdown
   #
   # @param [Range] range
@@ -108,30 +106,40 @@ class XPool
   #
   # Dispatch a unit of work in a subprocess.
   #
-  # @param 
+  # @param
   #   (see Process#schedule)
   #
-  # @return 
+  # @return
   #   (see Process#schedule)
   #
   def schedule(unit, *args)
     @channel.put unit: unit, args: args
   end
 
+  #
+  # @return [Fixnum]
+  #   Returns the number of alive subprocesses in the pool.
+  #
+  def size
+    @pool.count do |process|
+      process.alive?
+    end
+  end
+
 private
   def spawn
     pid = fork do
       trap :SIGUSR1 do
         XPool.log "#{::Process.pid} got request to shutdown."
-        @shutdown_requested = true 
+        @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 
+          # 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?
@@ -146,6 +154,22 @@ private
         end
       end
     end
-    Process.new pid 
+    Process.new pid
+  end
+
+  #
+  # Count the number of CPU cores available.
+  #
+  def number_of_cpu_cores
+    case RbConfig::CONFIG['host_os']
+    when /linux/
+      Dir.glob('/sys/devices/system/cpu/cpu[0-9]*').count
+    when /darwin|bsd/
+      Integer(`sysctl -n hw.ncpu`)
+    when /solaris/
+      Integer(`kstat -m cpu_info | grep -w core_id | uniq | wc -l`)
+    else
+      5
+    end
   end
 end

data/lib/xpool/process.rb

@@ -1,6 +1,6 @@
 class XPool::Process
   #
-  # @param [Fixnum] id 
+  # @param [Fixnum] id
   #   The Process ID.
   #
   def initialize(id)
@@ -10,8 +10,8 @@ class XPool::Process
   #
   # A graceful shutdown of the process.
   #
-  # The signal 'SIGUSR1' is caught in the subprocess and exit is 
-  # performed through Kernel#exit after the process has finished 
+  # The signal 'SIGUSR1' is caught in the subprocess and exit is
+  # performed through Kernel#exit after the process has finished
   # executing its work.
   #
   # @return [void]
@@ -28,13 +28,31 @@ class XPool::Process
   def shutdown!
     _shutdown 'SIGKILL'
   end
-  
+
+  #
+  # @return [Boolean]
+  #   Returns true when the process is alive.
+  #
+  def alive?
+    !dead?
+  end
+
+  #
+  # @return [Boolean]
+  #   Returns true when the process is no longer running.
+  #
+  def dead?
+    @dead
+  end
+
 private
   def _shutdown(sig)
     begin
       Process.kill sig, @id
       Process.wait @id
     rescue SystemCallError
+    ensure
+      @dead = true
     end
   end
 end

data/lib/xpool/version.rb

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

data/test/xpool_test.rb

@@ -10,7 +10,7 @@ class XPoolTest < Test::Unit::TestCase
     def initialize
       file = Tempfile.new '__xpool_test'
       @path = file.path
-      file.close
+      file.close false
     end
 
     def run
@@ -34,9 +34,21 @@ class XPoolTest < Test::Unit::TestCase
   def teardown
     @pool.shutdown
   end
-  
 
-  def test_queue 
+
+  def test_size_with_graceful_shutdown
+    assert_equal 5, @pool.size
+    @pool.shutdown
+    assert_equal 0, @pool.size
+  end
+
+  def test_size_with_forceful_shutdown
+    assert_equal 5, @pool.size
+    @pool.shutdown!
+    assert_equal 0, @pool.size
+  end
+
+  def test_queue
     @pool.resize! 1..1
     units = Array.new(5) { XUnit.new }
     units.each do |unit|
@@ -48,18 +60,18 @@ class XPoolTest < Test::Unit::TestCase
     end
   end
 
-  def test_parallelism 
-    5.times do 
+  def test_parallelism
+    5.times do
       @pool.schedule Unit.new
     end
     assert_nothing_raised Timeout::Error do
-      Timeout.timeout 2 do 
+      Timeout.timeout 2 do
         @pool.shutdown
       end
     end
   end
 
-  def test_resize! 
+  def test_resize!
     @pool.resize! 1..1
     assert_equal 1, @pool.instance_variable_get(:@pool).size
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xpool
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-01 00:00:00.000000000 Z
+date: 2012-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ichannel
@@ -35,6 +35,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- ChangeLog.txt
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -59,7 +60,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2070941546545092687
+      hash: -2000550100409961336
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -68,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2070941546545092687
+      hash: -2000550100409961336
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23