simple_work_queue 0.9.1

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+doc/
+pkg/
+config/

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2009-2010 Miguel Fonseca
+
+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.rdoc

@@ -0,0 +1,43 @@
+= Description
+
+A work queue is designed to coordinate work between a producer and a pool of worker threads.
+When some task needs to be performed, the producer adds an object containing the task routine to the work queue.
+Eventually, one of the worker threads removes the object from the work queue and executes the routine.
+If the work queue is empty, the worker thread will exit, if more jobs are added to the queue additional worker 
+threads will be created up to the configured maximum.
+
+Work queues are useful for several reasons:
+* To easily perform tasks asynchronously and concurrently in your application;
+* To let you focus on the work you actually want to perform without having to worry about the thread creation and management;
+* To minimize overhead, by reusing previously constructed threads rather than creating new ones;
+* To bound resource use, by setting a limit on the maximum number of simultaneously executing threads;
+
+= Requirements
+
+JRuby
+
+= Usage
+
+Install the gem:
+
+  gem install simple_work_queue
+
+Run the code:
+
+  require 'rubygems'
+  require 'simple_work_queue'
+  wq = SimpleWorkQueue.new
+  wq.enqueue_b { puts "Hello from the SimpleWorkQueue" }
+  wq.join
+
+Note that you generally want to bound the number of worker threads:
+
+  # Limit the maximum number of simultaneous worker threads
+  SimpleWorkQueue.new(10)
+
+= History
+
+SimpleWorkQueue is a fork of WorkQueue by Miguel Fonseca. SimpleWorkQueue removes the time out and bounded task queue.
+The timeout created issues under the concurrency implementation in JRuby. The time out mechanism was replaced using a
+non-blocking queue from the java.util.concurrent library. If a worker thread attempts to remove a task from the task queue
+and it is empty it will exit the worker thread.

data/Rakefile

@@ -0,0 +1,11 @@
+# require 'rubygems'
+# require 'rake'
+# require 'rake/clean'
+require 'lib/simple_work_queue'
+require 'bundler/gem_tasks'
+
+# Load all rakefile extensions
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].each { |ext| load ext }
+
+# Set default task
+task :default => ["test:unit"]

data/lib/simple_work_queue.rb

@@ -0,0 +1,206 @@
+##
+# = Name
+# SimpleWorkQueue
+#
+# == Description
+# This file contains an implementation of a work queue structure.
+#
+# == Version
+# 1.0.0
+#
+# == Author
+# Miguel Fonseca <fmmfonseca@gmail.com>
+# Mark Menard <mark.menard.tny@gmail.com>
+#
+# == Copyright
+# Copyright 2009-2010 Miguel Fonseca
+# Copyright 2011 Mark Menard
+#
+# == License
+# MIT (see LICENSE file)
+#
+
+require 'java'
+
+##
+# = SimpleWorkQueue
+#
+# == Description
+# A simple work queue, designed to coordinate work between a producer and a pool of worker threads.
+# SimpleWorkQueue is a fork of WorkQueue by Miguel Fonseca that has been simplified and made to work
+# with JRuby using a non-blocking queue from the Java Concurrency framework.
+#
+# SimpleWorkQueue unlike WorkQueue does not support time outs (unneeded because SimpleWorkQueue uses 
+# a non-blocking queue), or limits on the number of queued jobs. If you need these features under
+# JRuby you will need to find a different solution.
+#
+# == Usage
+#  wq = SimpleWorkQueue.new
+#  wq.enqueue_b { puts "Hello from the SimpleWorkQueue" }
+#  wq.join
+#
+class SimpleWorkQueue
+
+  ##
+  # Creates a new work queue with the desired parameters.
+  #
+  #  wq = SimpleWorkQueue.new(5)
+  #
+  def initialize(max_threads=nil)
+    self.max_threads = max_threads
+    @threads = []
+    @threads_lock = Mutex.new
+    @tasks = java.util.concurrent.ConcurrentLinkedQueue.new
+    @threads.taint
+    @tasks.taint
+    self.taint
+  end
+
+  ##
+  # Returns the maximum number of worker threads.
+  # This value is set upon initialization and cannot be changed afterwards.
+  #
+  #  wq = SimpleWorkQueue.new()
+  #  wq.max_threads		#=> Infinity
+  #  wq = SimpleWorkQueue.new(1)
+  #  wq.max_threads		#=> 1
+  #
+  def max_threads
+    @max_threads
+  end
+
+  ##
+  # Returns the current number of worker threads.
+  # This value is just a snapshot, and may change immediately upon returning.
+  #
+  #  wq = SimpleWorkQueue.new(10)
+  #  wq.cur_threads		#=> 0
+  #  wq.enqueue_b {}
+  #  wq.cur_threads		#=> 1
+  #
+  def cur_threads
+    @threads.size
+  end
+
+  ##
+  # Returns the current number of queued tasks.
+  # This value is just a snapshot, and may change immediately upon returning.
+  #
+  #  wq = SimpleWorkQueue.new(1)
+  #  wq.enqueue_b { sleep(1) }
+  #  wq.cur_tasks		#=> 0
+  #  wq.enqueue_b {}
+  #  wq.cur_tasks		#=> 1
+  #
+  def cur_tasks
+    @tasks.size
+  end
+
+  ##
+  # Schedules the given Proc for future execution by a worker thread.
+  # If there is no space left in the queue, waits until space becomes available.
+  #
+  #  wq = SimpleWorkQueue.new(1)
+  #  wq.enqueue_p(Proc.new {})
+  #
+  def enqueue_p(proc, *args)
+    @tasks.add([proc,args])
+    spawn_thread
+    self
+  end
+
+  ##
+  # Schedules the given Block for future execution by a worker thread.
+  # If there is no space left in the queue, waits until space becomes available.
+  #
+  #  wq = SimpleWorkQueue.new(1)
+  #  wq.enqueue_b {}
+  #
+  def enqueue_b(*args, &block)
+    @tasks.add([block,args])
+    spawn_thread
+    self
+  end
+
+  ##
+  # Waits until the tasks queue is empty and all worker threads have finished.
+  #
+  #  wq = SimpleWorkQueue.new(1)
+  #  wq.enqueue_b { sleep(1) }
+  #  wq.join
+  #
+  def join
+    cur_threads.times { dismiss_thread }
+    @threads.dup.each { |thread| thread.join if thread }
+    self
+  end
+
+  ##
+  # Stops all worker threads immediately, aborting any ongoing tasks.
+  #
+  #  wq = SimpleWorkQueue.new(1)
+  #  wq.enqueue_b { sleep(1) }
+  #  wq.stop
+  #
+  def stop
+    @threads.dup.each { |thread| thread.exit.join }
+    @tasks.clear
+    self
+  end
+
+  private
+
+  ##
+  # Sets the maximum number of worker threads.
+  #
+  def max_threads=(value)
+    raise ArgumentError, "the maximum number of threads must be positive" if value and value <= 0
+    @max_threads = value || 1.0/0
+  end
+
+  ##
+  # Enrolls a new worker thread.
+  # The request is only carried out if necessary.
+  #
+  def spawn_thread
+    if cur_threads < max_threads and cur_tasks > 0
+      @threads_lock.synchronize {
+        @threads << Thread.new do
+          begin
+            work()
+          ensure
+            @threads_lock.synchronize { @threads.delete(Thread.current) }
+          end
+        end
+      }
+    end
+  end
+
+  ##
+  # Instructs an idle worker thread to exit.
+  # The request is only carried out if necessary.
+  #
+  def dismiss_thread
+    @tasks << [Proc.new { Thread.exit }, nil] if cur_threads > 0
+  end
+
+  ##
+  # Repeatedly process the tasks queue.
+  #
+  def work
+    loop do
+      begin
+        proc, args = @tasks.poll
+        if proc
+          proc.call(*args)
+        else
+          break
+        end
+      rescue Exception
+        # suppress exception
+      end
+      break if cur_threads > max_threads
+    end
+  end
+
+end

data/lib/simple_work_queue/version.rb

@@ -0,0 +1,3 @@
+class SimpleWorkQueue
+  VERSION = "0.9.1"
+end

data/simple_work_queue.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "simple_work_queue/version"
+
+Gem::Specification.new do |s|
+  s.name        = "simple_work_queue"
+  s.version     = SimpleWorkQueue::VERSION
+  s.authors     = ["Mark Menard"]
+  s.email       = ["mark@mjm.net"]
+  s.homepage    = "http://www.github.com/MarkMenard/simple_work_queue"
+  s.summary     = %q{A simple work queue for JRuby based on work_queue by Miguel Fonseca.}
+  s.description = %q{A simple work queue for JRuby to manage a pool of worker threads.}
+
+  s.rubyforge_project = "simple_work_queue"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/tasks/rdoc.rake

@@ -0,0 +1,11 @@
+# require 'rake/rdoctask'
+# 
+# CLEAN.include("doc")
+# 
+# # For a list of all attributes refer to http://rake.rubyforge.org/classes/Rake/RDocTask.html
+# Rake::RDocTask.new do |rd|
+#   rd.title = "work_queue-#{SimpleWorkQueue::VERSION} Documentation"
+#   rd.main = "README.rdoc"
+#   rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#   rd.rdoc_dir = "doc"
+# end

data/tasks/test.rake

@@ -0,0 +1,13 @@
+require 'rake/testtask'
+
+namespace(:test) do
+
+  # For a list of all attributes refer to http://rake.rubyforge.org/classes/Rake/TestTask.html
+  Rake::TestTask.new(:unit) do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/tc_*.rb']
+    t.verbose = true
+    t.warning = true
+  end
+
+end

data/test.rb

@@ -0,0 +1,27 @@
+require 'lib/simple_work_queue'
+
+10.times do |j|
+  wq = SimpleWorkQueue.new(50)
+  2500.times do |i|
+    wq.enqueue_b do
+      puts "!!!!!!!!!!!!!!!!!!!! DONE - Finished run #{j} !!!!!!!!!!!!!!!!!!!!" if i == 2499
+    end
+  end
+  wq.join
+end
+
+puts "Finished noop test."
+
+10.times do |j|
+  wq = SimpleWorkQueue.new(100)
+  500.times do |i|
+    wq.enqueue_b do
+      sleep rand
+      puts "!!!!!!!!!!!!!!!!!!!! DONE - Finished run #{j} !!!!!!!!!!!!!!!!!!!!" if i == 499
+    end
+  end
+  wq.join
+end
+
+# Under JRuby 1.6.3 we never get here.
+puts "*********************** DONE *********************"

data/test/tc_simple_work_queue.rb

@@ -0,0 +1,67 @@
+##
+# = Name
+# TC_SimpleWorkQueue
+#
+# == Description
+# This file contains unit tests for the SimpleWorkQueue class.
+#
+# == Author
+# Miguel Fonseca <fmmfonseca@gmail.com>
+#
+# == Copyright
+# Copyright 2009-2010 Miguel Fonseca
+#
+# == License
+# MIT (see LICENSE file)
+
+require 'test/unit'
+require 'lib/simple_work_queue'
+
+class TC_SimpleWorkQueue < Test::Unit::TestCase
+
+  # def setup
+  # end
+
+  # def teardown
+  # end
+
+  def test_enqueue
+    s = String.new
+    wq = SimpleWorkQueue.new
+    # using proc
+    wq.enqueue_p(Proc.new { |str| str.replace("Hello #1") }, s)
+    wq.join
+    assert_equal("Hello #1", s)
+    # using block
+    wq.enqueue_b(s) { |str| str.replace("Hello #2") }
+    wq.join
+    assert_equal("Hello #2", s)
+  end
+
+  def test_max_threads
+    assert_raise(ArgumentError) { SimpleWorkQueue.new(0) }
+    assert_raise(ArgumentError) { SimpleWorkQueue.new(-1) }
+    wq = SimpleWorkQueue.new(1)
+    assert_equal(0, wq.cur_threads)
+    wq.enqueue_b { sleep(0.01) }
+    assert_equal(1, wq.cur_threads)
+    wq.enqueue_b { sleep(0.01) }
+    assert_equal(1, wq.cur_threads)
+    wq.join
+  end
+
+  def test_stress
+    a = []
+    m = Mutex.new
+    wq = SimpleWorkQueue.new(250)
+    (1..1000).each do
+      wq.enqueue_b do
+        sleep(0.01)
+        m.synchronize { a.push nil }
+      end
+    end
+    wq.join
+    assert_equal(1000, a.size)
+  end
+
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: simple_work_queue
+version: !ruby/object:Gem::Version 
+  hash: 57
+  prerelease: 
+  segments: 
+  - 0
+  - 9
+  - 1
+  version: 0.9.1
+platform: ruby
+authors: 
+- Mark Menard
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-19 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: A simple work queue for JRuby to manage a pool of worker threads.
+email: 
+- mark@mjm.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/simple_work_queue.rb
+- lib/simple_work_queue/version.rb
+- simple_work_queue.gemspec
+- tasks/rdoc.rake
+- tasks/test.rake
+- test.rb
+- test/tc_simple_work_queue.rb
+has_rdoc: true
+homepage: http://www.github.com/MarkMenard/simple_work_queue
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: simple_work_queue
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A simple work queue for JRuby based on work_queue by Miguel Fonseca.
+test_files: 
+- test/tc_simple_work_queue.rb