thpool 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,6 @@
+source 'http://rubygems.org'
+
+group :development do
+  gem 'bundler', '>= 1.0.0'
+  gem 'jeweler', '>= 1.8.4'
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Scott Tadman
+
+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,87 @@
+# Thpool
+
+This is a simple threaded pool worker system that can process tasks in the
+order they are received.
+
+## Example
+
+```
+pool = Thpool.new
+
+pool.perform do
+  # ... Action to be enqueued here
+end
+```
+
+The worker pool has some sensible defaults as to how many workers will be
+created, zero when there's no work, up to twenty when there's enough work
+to be performed. These settings can be customized.
+
+Constructor options:
+
+  * `:worker_class` - What kind of worker to spawn. Should be a Worker subclass.
+  * `:workers_min` - The minimum number of workers to have running.
+  * `:workers_max` - The maximum number of workers to have running.
+  * `:count_per_worker` - The ratio of tasks to workers.
+
+The default `EnThpool::Worker` class should suffice for most tasks.
+If necessary, this can be subclassed. This would be useful if the worker
+needs to perform some kind of resource initialization before it's able to
+complete any tasks, such as establishing a database connection.
+
+There is a method `after_initialize` that will execute on the worker thread
+immediately after the worker is created. This is useful for performing
+post-initialization functions that would otherwise block the main thread:
+
+```
+class ExampleDatabaseWorker < Thpool::Worker
+  def after_initialize
+     # Create a database handle.
+     @db = DatabaseDriver::Handle.new
+
+     # Pass in the database handle as the arguments to the blocks being
+     # processed.
+     @args = [ @db ]
+  end
+end
+```
+
+It's also possible to re-write the `perform` method to pass in additional
+arguments.
+
+If you need to do something immediately before or after processing of a block,
+two methods are available. As an example this can be used to record the amount
+of time it took to complete a task:
+
+```
+class ExampleDatabaseWorker < Thpool::Worker
+  def before_perform(block)
+    @start_time = Time.now
+  end
+
+  def after_perform(block)
+    puts "Took %ds" % (Time.now - @start_time)
+  end
+end
+```
+
+If exceptions are generated within the worker thread either because of
+processing a task or otherwise, these are passed back to the Thpool
+object via the `handle_exception` method. The default behavior is to re-raise
+these, but it's also possible to perform some additional handling here to
+rescue from or ignore them:
+
+```
+class ExampleDatabasePool < Thpool
+  def handle_exception(worker, exception, block = nil)
+    # Pass through to a custom exception logger
+    ExceptionHandler.log(exception)
+  end
+end
+```
+
+## Copyright
+
+Copyright (c) 2013 Scott Tadman, The Working Group Inc.
+See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'jeweler'
+
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "thpool"
+  gem.homepage = "http://github.com/twg/thpool"
+  gem.license = "MIT"
+  gem.summary = %Q{Threaded Pool/Worker System}
+  gem.description = %Q{Simple thread pool/worker system}
+  gem.email = "scott@twg.ca"
+  gem.authors = [ "Scott Tadman" ]
+  # dependencies defined in Gemfile
+end
+
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end

data/VERSION

@@ -0,0 +1,2 @@
+0.1.0
+

data/lib/thpool.rb

@@ -0,0 +1,147 @@
+require 'thread'
+
+class Thpool
+  # == Submodules ===========================================================
+
+  autoload(:Worker, 'thpool/worker')
+
+  # == Constants ============================================================
+
+  OPTIONS_DEFAULT = {
+    :worker_class => Thpool::Worker,
+    :workers_min => 0,
+    :workers_max => 20,
+    :count_per_worker => 1,
+    :args => [ ]
+  }
+
+  # == Properties ===========================================================
+
+  attr_reader *OPTIONS_DEFAULT.keys
+
+  # == Instance Methods =====================================================
+
+  # Creates a new instance of Pool with an optional set of options:
+  # * :worker_class - The class of worker to spawn when tasks arrive.
+  # * :workers_min - The minimum number of workers to have running.
+  # * :workers_max - The maximum number of workers to spawn.
+  # * :count_per_worker - Ratio of items in queue to workers.
+  # * :args - An array of arguments to be passed through to the workers.
+  def initialize(options = nil)
+    @queue = Queue.new
+    @workers = [ ]
+
+    options = options ? OPTIONS_DEFAULT.merge(options) : OPTIONS_DEFAULT
+
+    @worker_class = options[:worker_class]
+    @workers_min = options[:workers_min]
+    @workers_max = options[:workers_max]
+    @count_per_worker = options[:count_per_worker]
+    @args = options[:args]
+
+    @workers_min.times do
+      self.worker_create!
+    end
+  end
+
+  # Returns the number of active worker threads.
+  def workers_count
+    @workers.length
+  end
+
+  # Returns the number of workers required for the current loading.
+  def workers_needed
+    n = ((@queue.length + @workers.length - @queue.num_waiting) / @count_per_worker)
+
+    if (n > @workers_max)
+      @workers_max
+    elsif (n < @workers_min)
+      @workers_min
+    else
+      n
+    end  
+  end
+
+  # Makes a blocking call to pop an item from the queue, returning that item.
+  # If the queue is empty, also has the effect of sleeping the calling thread
+  # until something is pushed into the queue.
+  def block_pop
+    @queue.pop
+  end
+
+  # Returns true if more workers are needed to satisfy the current backlog,
+  # or false otherwise.
+  def workers_needed?
+    @workers.length < self.workers_needed
+  end
+
+  def worker_needed?(worker)
+    @queue.length > 0 or @workers.length <= self.workers_needed
+  end
+
+  # Returns an array of the current workers.
+  def workers
+    @workers.dup
+  end
+
+  # Returns the current number of workers.
+  def workers_count
+    @workers.length
+  end
+
+  # Returns true if there are any workers, false otherwise.
+  def workers?
+    @workers.any?
+  end
+
+  # Returns true if there is some outstanding work to be performed, false
+  # otherwise.
+  def busy?
+    @queue.num_waiting < @workers.length
+  end
+
+  # Returns the number of workers that are waiting for something to do.
+  def waiting
+    @queue.num_waiting
+  end
+
+  # Returns true if anything is queued, false otherwise. Note that this does
+  # not count anything that might be active within a worker.
+  def queue?
+    @queue.length > 0
+  end
+
+  # Returns the number of items in the queue. Note that this does not count
+  # anything that might be active within a worker.
+  def queue_size
+    @queue.size
+  end
+  
+  # Receives reports of exceptions from workers. Default behavior is to re-raise.
+  def report_exception!(worker, exception, block = nil)
+    raise(exception)
+  end
+
+  # Schedules a block to be acted upon by the workers.
+  def perform
+    @queue << Proc.new
+
+    if (self.workers_count < self.workers_needed)
+      self.worker_create!
+    end
+
+    true
+  end
+
+  # Called by a worker when it's finished. Should not be called otherwise.
+  def worker_finished!(worker)
+    @workers.delete(worker)
+    worker.join
+  end
+
+protected
+  # Creates a new worker and puts it into the list of available workers.
+  def worker_create!
+    @workers << worker_class.new(self, *@args)
+  end
+end

data/lib/thpool/worker.rb

@@ -0,0 +1,71 @@
+class Thpool::Worker
+  # == Properties ===========================================================
+
+  attr_reader :pool
+  attr_reader :args
+  attr_reader :block
+
+  # == Instance Methods =====================================================
+
+  # Creates a new worker attached to the provided pool. Optional arguments
+  # may be supplied, which are passed on to the blocks it processes.
+  def initialize(pool, *args)
+    @pool = pool
+    @args = args
+
+    @thread = Thread.new do
+      Thread.abort_on_exception = true
+      begin
+        self.after_initialize
+
+        while (block = @pool.block_pop)
+          begin
+            @block = block
+            self.before_perform(block)
+            perform(&block)
+            self.after_perform(block)
+            @block = nil
+
+            unless (@pool.worker_needed?(self))
+              @pool.worker_finished!(self)
+              break
+            end
+          rescue => exception
+            @pool.handle_exception(self, exception, block)
+          end
+        end
+      rescue => exception
+        @pool.handle_exception(self, exception, nil)
+      end
+    end
+  end
+
+  # Calls the Proc pulled from the queue. Subclasses can implement their own
+  # method here which might pass in arguments to the block for contextual
+  # purposes.
+  def perform
+    yield(*@args)
+  end
+
+  # This method is called after the worker is initialized within the thread
+  # used by the worker. It can be customized in sub-classes as required.
+  def after_initialize
+  end
+
+  # This method is called just before the worker executes the given block.
+  # This should be customized in sub-classes to do any additional processing
+  # required.
+  def before_perform(block)
+  end
+
+  # This method is called just after the worker has finished executing the
+  # given block This should be customized in sub-classes to do any additional
+  # processing required.
+  def after_perform(block)
+  end
+
+  # Called by the pool to reap this thread when it is finished.
+  def join
+    @thread.join
+  end
+end

data/test/helper.rb

@@ -0,0 +1,31 @@
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'thpool'
+
+class Test::Unit::TestCase
+  def assert_eventually(time = nil, message = nil, &block)
+    start_time = Time.now.to_i
+
+    while (!block.call)
+      select(nil, nil, nil, 0.1)
+      
+      if (time and (Time.now.to_i - start_time > time))
+        flunk(message || 'assert_eventually timed out')
+      end
+    end
+  end
+end

data/test/unit/test_thpool.rb

@@ -0,0 +1,142 @@
+require_relative '../helper'
+
+class TestThpool < Test::Unit::TestCase
+  def test_defaults
+    pool = Thpool.new
+
+    assert_equal false, pool.queue?
+    assert_equal 0, pool.queue_size
+
+    assert_equal 0, pool.workers_count
+    assert_equal 0, pool.workers_needed
+    assert_equal false, pool.workers_needed?
+    assert_equal 0, pool.waiting
+
+    assert_equal [ ], pool.workers
+
+    options_default = Thpool::OPTIONS_DEFAULT
+
+    assert_equal options_default[:worker_class], pool.worker_class
+    assert_equal options_default[:workers_min], pool.workers_min
+    assert_equal options_default[:workers_max], pool.workers_max
+    assert_equal options_default[:count_per_worker], pool.count_per_worker
+    assert_equal options_default[:args], pool.args
+  end
+
+  class ExampleWorker < Thpool::Worker
+    attr_reader :after_initialized
+    attr_reader :before_performed
+    attr_reader :after_performed
+
+    def after_initialize
+      @after_initialized = :after_initialized
+    end
+
+    def before_perform(block)
+      @before_performed = :before_performed
+    end
+
+    def after_perform(block)
+      @after_performed = :after_performed
+    end
+  end
+
+  def test_options
+    pool = Thpool.new(
+      :worker_class => ExampleWorker,
+      :workers_min => 1,
+      :workers_max => 5,
+      :count_per_worker => 2,
+      :args => [ :example ]
+    )
+
+    assert_equal false, pool.queue?
+    assert_equal 0, pool.queue_size
+
+    assert_equal 1, pool.workers_count
+    assert_equal 1, pool.workers_needed
+    assert_equal false, pool.workers_needed?
+
+    assert_equal ExampleWorker, pool.worker_class
+    assert_equal 1, pool.workers_min
+    assert_equal 5, pool.workers_max
+    assert_equal 2, pool.count_per_worker
+    assert_equal [ :example ], pool.args
+
+    worker = pool.workers[0]
+
+    assert worker
+    assert worker.is_a?(ExampleWorker)
+
+    assert_equal pool, worker.pool
+    assert_equal nil, worker.block
+    assert_equal [ :example ], worker.args
+
+    assert_eventually(1) do
+      worker.after_initialized
+    end
+
+    assert_equal :after_initialized, worker.after_initialized
+    assert_equal nil, worker.before_performed
+    assert_equal nil, worker.after_performed
+  end
+
+  def test_simple_tasks
+    pool = Thpool.new
+    count = 0
+
+    100.times do
+      pool.perform do
+        count += 1
+      end
+    end
+
+    assert_eventually do
+      count == 100
+    end
+  end
+
+  def test_with_context
+    pool = Thpool.new(
+      :args => [ :test, 'arguments' ]
+    )
+
+    args = nil
+
+    pool.perform do |*_args|
+      args = _args
+    end
+
+    assert_eventually(1) do
+      args
+    end
+
+    assert_equal [ :test, 'arguments' ], args
+  end
+
+  def test_with_recursion
+    pool = Thpool.new
+
+    times = 100
+    queued = 0
+    count = 0
+
+    times.times do |n|
+      pool.perform do
+        n.times do
+          queued += 1
+          pool.perform do |*args|
+            count += 1
+          end
+        end
+      end
+    end
+
+    assert_eventually(600) do
+      !pool.queue? and !pool.busy?
+    end
+
+    assert_equal (0..times - 1).inject(0) { |s, r| s + r }, queued
+    assert_equal queued, count 
+  end
+end

data/test/unit/test_thpool_worker.rb

@@ -0,0 +1,14 @@
+require_relative '../helper'
+
+class TestThpoolWorker < Test::Unit::TestCase
+  def test_defaults
+    pool = Thpool.new
+    args = %w[ test arguments ]
+
+    worker = Thpool::Worker.new(pool, *args)
+
+    assert_equal pool, worker.pool
+    assert_equal nil, worker.block
+    assert_equal args, worker.args
+  end
+end

data/test/unit/test_worker_pool.rb

@@ -0,0 +1,142 @@
+require_relative '../helper'
+
+class TestThpool < Test::Unit::TestCase
+  def test_defaults
+    pool = Thpool.new
+
+    assert_equal false, pool.queue?
+    assert_equal 0, pool.queue_size
+
+    assert_equal 0, pool.workers_count
+    assert_equal 0, pool.workers_needed
+    assert_equal false, pool.workers_needed?
+    assert_equal 0, pool.waiting
+
+    assert_equal [ ], pool.workers
+
+    options_default = Thpool::OPTIONS_DEFAULT
+
+    assert_equal options_default[:worker_class], pool.worker_class
+    assert_equal options_default[:workers_min], pool.workers_min
+    assert_equal options_default[:workers_max], pool.workers_max
+    assert_equal options_default[:count_per_worker], pool.count_per_worker
+    assert_equal options_default[:args], pool.args
+  end
+
+  class ExampleWorker < Thpool::Worker
+    attr_reader :after_initialized
+    attr_reader :before_performed
+    attr_reader :after_performed
+
+    def after_initialize
+      @after_initialized = :after_initialized
+    end
+
+    def before_perform(block)
+      @before_performed = :before_performed
+    end
+
+    def after_perform(block)
+      @after_performed = :after_performed
+    end
+  end
+
+  def test_options
+    pool = Thpool.new(
+      :worker_class => ExampleWorker,
+      :workers_min => 1,
+      :workers_max => 5,
+      :count_per_worker => 2,
+      :args => [ :example ]
+    )
+
+    assert_equal false, pool.queue?
+    assert_equal 0, pool.queue_size
+
+    assert_equal 1, pool.workers_count
+    assert_equal 1, pool.workers_needed
+    assert_equal false, pool.workers_needed?
+
+    assert_equal ExampleWorker, pool.worker_class
+    assert_equal 1, pool.workers_min
+    assert_equal 5, pool.workers_max
+    assert_equal 2, pool.count_per_worker
+    assert_equal [ :example ], pool.args
+
+    worker = pool.workers[0]
+
+    assert worker
+    assert worker.is_a?(ExampleWorker)
+
+    assert_equal pool, worker.pool
+    assert_equal nil, worker.block
+    assert_equal [ :example ], worker.args
+
+    assert_eventually(1) do
+      worker.after_initialized
+    end
+
+    assert_equal :after_initialized, worker.after_initialized
+    assert_equal nil, worker.before_performed
+    assert_equal nil, worker.after_performed
+  end
+
+  def test_simple_tasks
+    pool = Thpool.new
+    count = 0
+
+    100.times do
+      pool.perform do
+        count += 1
+      end
+    end
+
+    assert_eventually do
+      count == 100
+    end
+  end
+
+  def test_with_context
+    pool = Thpool.new(
+      :args => [ :test, 'arguments' ]
+    )
+
+    args = nil
+
+    pool.perform do |*_args|
+      args = _args
+    end
+
+    assert_eventually(1) do
+      args
+    end
+
+    assert_equal [ :test, 'arguments' ], args
+  end
+
+  def test_with_recursion
+    pool = Thpool.new
+
+    times = 100
+    queued = 0
+    count = 0
+
+    times.times do |n|
+      pool.perform do
+        n.times do
+          queued += 1
+          pool.perform do |*args|
+            count += 1
+          end
+        end
+      end
+    end
+
+    assert_eventually(600) do
+      !pool.queue? and !pool.busy?
+    end
+
+    assert_equal (0..times - 1).inject(0) { |s, r| s + r }, queued
+    assert_equal queued, count 
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: thpool
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Scott Tadman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.8.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.8.4
+description: Simple thread pool/worker system
+email: scott@twg.ca
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- .document
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/thpool.rb
+- lib/thpool/worker.rb
+- test/helper.rb
+- test/unit/test_thpool.rb
+- test/unit/test_thpool_worker.rb
+- test/unit/test_worker_pool.rb
+homepage: http://github.com/twg/thpool
+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'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Threaded Pool/Worker System
+test_files: []