xpool 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Rob Gleeson
+
+MIT License
+
+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,77 @@
+__OVERVIEW__
+
+| 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)
+| Author          | Rob Gleeson             
+
+
+__DESCRIPTION__
+
+A lightweight UNIX(X) Process Pool implementation. 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.
+
+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. 
+
+
+__EXAMPLES__
+
+_1._
+
+A demo of how you'd create a pool of 10 subprocesses:
+
+    #
+    # Make sure you define your units of work before
+    # you create a process pool or you'll get strange
+    # serialization errors.
+    #
+    class Unit
+      def run
+        sleep 1
+      end
+    end
+    pool = XPool.new 10
+    5.times { pool.schedule Unit.new }
+    pool.shutdown
+
+_2._
+
+A demo of how you'd resize the pool from 10 to 5 subprocesses at runtime:
+
+    class Unit
+      def run
+        sleep 5
+      end
+    end
+    pool = XPool.new 10
+    pool.resize! 1..5
+    pool.shutdown
+
+_3._
+
+A demo of how you'd gracefully shutdown but force a hard shutdown if 3 seconds
+pass by & all subprocesses have not exited:
+
+    class Unit
+      def run
+        sleep 5
+      end
+    end
+    pool = XPool.new 10
+    pool.schedule Unit.new
+    pool.shutdown 3
+
+__INSTALL__
+
+    $ gem install xpool
+
+__LICENSE__
+
+MIT. See `LICENSE.txt` 

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+task :test do
+  $LOAD_PATH.unshift 'lib'
+  Dir["test/*_test.rb"].each do |file|
+    require_relative file
+  end
+end
+task :default => :test

data/lib/xpool.rb

@@ -0,0 +1,151 @@
+class XPool
+  require 'json'
+  require 'ichannel'
+  require 'timeout'
+  require 'logger'
+  require_relative "xpool/version"
+  require_relative "xpool/process"
+
+  def self.debug
+    if block_given?
+      begin
+        @debug = true
+        yield
+      ensure
+        @debug = false
+      end
+    else
+      @debug
+    end
+  end
+
+  def self.debug=(boolean)
+    @debug = boolean
+  end
+
+  def self.log(msg, type = :info) 
+    @logger = @logger || Logger.new(STDOUT)
+    if @debug
+      @logger.public_send type, msg
+    end
+  end
+
+  #
+  # @param [Fixnum] size
+  #   The number of subprocesses to spawn.
+  #
+  # @return [XPool]
+  #
+  def initialize(size=10)
+    @channel = IChannel.new Marshal
+    @pool = Array.new size do 
+      spawn
+    end
+  end
+
+  #
+  # A graceful shutdown of the pool.
+  #
+  # All busy subprocesses finish up any code they're running & exit normally 
+  # afterwards.
+  #
+  # @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
+        end
+      rescue Timeout::Error
+        XPool.log "'#{timeout}' seconds elapsed, switching to hard shutdown."
+        shutdown!
+      end
+    else
+      @pool.each(&:shutdown)
+    end
+  end
+
+  #
+  # A forceful shutdown of the pool (through SIGKILL).
+  #
+  # @return [void]
+  #
+  def shutdown!
+    @pool.each(&:shutdown!)
+  end
+
+  #
+  # Resize the pool.
+  # 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.shutdown
+  #
+  # @param [Range] range
+  #   The new size of the pool.
+  #
+  # @return [void]
+  #
+  def resize!(range)
+    shutdown!
+    @pool = range.to_a.map do
+      spawn
+    end
+  end
+
+  #
+  # Dispatch a unit of work in a subprocess.
+  #
+  # @param 
+  #   (see Process#schedule)
+  #
+  # @return 
+  #   (see Process#schedule)
+  #
+  def schedule(unit, *args)
+    @channel.put unit: unit, args: args
+  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 
+  end
+end

data/lib/xpool/process.rb

@@ -0,0 +1,40 @@
+class XPool::Process
+  #
+  # @param [Fixnum] id 
+  #   The Process ID.
+  #
+  def initialize(id)
+    @id = id
+  end
+
+  #
+  # 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 
+  # executing its work.
+  #
+  # @return [void]
+  #
+  def shutdown
+    _shutdown 'SIGUSR1'
+  end
+
+  #
+  # A non-graceful shutdown through SIGKILL.
+  #
+  # @return [void]
+  #
+  def shutdown!
+    _shutdown 'SIGKILL'
+  end
+  
+private
+  def _shutdown(sig)
+    begin
+      Process.kill sig, @id
+      Process.wait @id
+    rescue SystemCallError
+    end
+  end
+end

data/lib/xpool/version.rb

@@ -0,0 +1,3 @@
+class XPool
+  VERSION = "0.1.0"
+end

data/test/setup.rb

@@ -0,0 +1,5 @@
+require 'bundler/setup'
+require 'xpool'
+require 'test/unit'
+require 'fileutils'
+XPool.debug = ENV.has_key? "DEBUG"

data/test/xpool_test.rb

@@ -0,0 +1,66 @@
+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
+    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
+  end
+  
+
+  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
+  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
+  end
+
+  def test_resize! 
+    @pool.resize! 1..1
+    assert_equal 1, @pool.instance_variable_get(:@pool).size
+  end
+end

data/xpool.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/xpool/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Robert Gleeson"]
+  gem.email         = ["rob@flowof.info"]
+  gem.description   = %q{A lightweight UNIX(X) Process Pool implementation}
+  gem.summary       = gem.description
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "xpool"
+  gem.require_paths = ["lib"]
+  gem.version       = XPool::VERSION
+  gem.add_runtime_dependency 'ichannel', '~> 4.1.0'
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: xpool
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Robert Gleeson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ichannel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+description: A lightweight UNIX(X) Process Pool implementation
+email:
+- rob@flowof.info
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/xpool.rb
+- lib/xpool/process.rb
+- lib/xpool/version.rb
+- test/setup.rb
+- test/xpool_test.rb
+- xpool.gemspec
+homepage: ''
+licenses: []
+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: 977068148446885427
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 977068148446885427
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A lightweight UNIX(X) Process Pool implementation
+test_files:
+- test/setup.rb
+- test/xpool_test.rb