work_queue 1.0.0 → 2.0.1

data/README.rdoc

@@ -4,7 +4,7 @@ A work queue is designed to coordinate work between a producer and a pool of wor
 When some task needs to be performed, the producer adds an object containing the task routine to the work queue.
 If the work queue is full, the producer will block until a worker thread removes an object from the queue.
 Eventually, one of the worker threads removes the object from the work queue and executes the routine.
-If the work queue is empty, a worker thread will block until an object is made available by the producer or until the keep-alive time expires.
+If the work queue is empty, a worker thread will block until an object is made available by the producer.
 
 Work queues are useful for several reasons:
 * To easily perform tasks asynchronously and concurrently in your application;
@@ -32,5 +32,3 @@ Note that you generally want to bound the resources used:
   WorkQueue.new(10)
   # Limit the maximum number of queued tasks
   WorkQueue.new(nil,20)
-  # Limit the maximum time to preserve idle worker threads
-  WorkQueue.new(nil,nil,10)

data/lib/work_queue.rb

@@ -6,20 +6,20 @@
 # This file contains an implementation of a work queue structure.
 #
 # == Version
-# 1.0.0
+# 2.0.0
 #
 # == Author
 # Miguel Fonseca <fmmfonseca@gmail.com>
 #
 # == Copyright
-# Copyright 2009-2010 Miguel Fonseca
+# Copyright 2009-2011 Miguel Fonseca
 #
 # == License
 # MIT (see LICENSE file)
 #
 
 require 'thread'
-require 'timeout'
+require 'monitor'
 
 ##
 # = WorkQueue
@@ -33,211 +33,204 @@ require 'timeout'
 #  wq.join
 #
 class WorkQueue
-
-  VERSION = "1.0.0"
-
-  ##
-  # Creates a new work queue with the desired parameters.
-  #
-  #  wq = WorkQueue.new(5,10,20)
-  #
-  def initialize(max_threads=nil, max_tasks=nil, keep_alive=60)
-    self.max_threads = max_threads
-    self.max_tasks = max_tasks
-    self.keep_alive = keep_alive
-    @threads = []
-    @threads_lock = Mutex.new
-    @tasks = max_tasks ? SizedQueue.new(max_tasks) : Queue.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 = WorkQueue.new()
-  #  wq.max_threads		#=> Infinity
-  #  wq = WorkQueue.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 = WorkQueue.new(10)
-  #  wq.cur_threads		#=> 0
-  #  wq.enqueue_b {}
-  #  wq.cur_threads		#=> 1
-  #
-  def cur_threads
-    @threads.size
-  end
-
-  ##
-  # Returns the maximum number of queued tasks.
-  # This value is set upon initialization and cannot be changed afterwards.
-  #
-  #  wq = WorkQueue.new()
-  #  wq.max_tasks		#=> Infinity
-  #  wq = WorkQueue.new(nil,1)
-  #  wq.max_tasks		#=> 1
-  #
-  def max_tasks
-    @max_tasks
-  end
-
-  ##
-  # Returns the current number of queued tasks.
-  # This value is just a snapshot, and may change immediately upon returning.
-  #
-  #  wq = WorkQueue.new(1)
-  #  wq.enqueue_b { sleep(1) }
-  #  wq.cur_tasks		#=> 0
-  #  wq.enqueue_b {}
-  #  wq.cur_tasks		#=> 1
-  #
-  def cur_tasks
-    @tasks.size
-  end
-
-  ##
-  # Returns the number of seconds to keep worker threads alive waiting for new tasks.
-  # This value is set upon initialization and cannot be changed afterwards.
-  #
-  #  wq = WorkQueue.new()
-  #  wq.keep_alive		#=> 60
-  #  wq = WorkQueue.new(nil,nil,1)
-  #  wq.keep_alive		#=> 1
-  #
-  def keep_alive
-    @keep_alive
-  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 = WorkQueue.new(1)
-  #  wq.enqueue_p(Proc.new {})
-  #
-  def enqueue_p(proc, *args)
-    @tasks << [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 = WorkQueue.new(1)
-  #  wq.enqueue_b {}
-  #
-  def enqueue_b(*args, &block)
-    @tasks << [block,args]
-    spawn_thread
-    self
-  end
-
-  ##
-  # Waits until the tasks queue is empty and all worker threads have finished.
-  #
-  #  wq = WorkQueue.new(1)
-  #  wq.enqueue_b { sleep(1) }
-  #  wq.join
-  #
-  def join
-    cur_threads.times { dismiss_thread }
-    @threads.dup.each { |thread| thread.join }
-    self
-  end
-
-  ##
-  # Stops all worker threads immediately, aborting any ongoing tasks.
-  #
-  #  wq = WorkQueue.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
-
-  ##
-  # Sets the maximum number of queued tasks.
-  #
-  def max_tasks=(value)
-    raise ArgumentError, "the maximum number of tasks must be positive" if value and value <= 0
-    @max_tasks = value || 1.0/0
-  end
-
-  ##
-  # Sets the maximum time to keep worker threads alive waiting for new tasks.
-  #
-  def keep_alive=(value)
-    raise ArgumentError, "the keep-alive time must be positive" if value and value <= 0
-    @keep_alive = 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 @tasks.num_waiting <= 0 and cur_tasks > 0
-      @threads_lock.synchronize {
-        @threads << Thread.new do
-          begin
-            work()
-          ensure
-            @threads_lock.synchronize { @threads.delete(Thread.current) }
-          end
+    
+    VERSION = "2.0.1"
+    
+    ##
+    # Creates a new work queue with the desired parameters.
+    #
+    #  wq = WorkQueue.new(5,10,20)
+    #
+    def initialize(max_threads=nil, max_tasks=nil)
+        self.max_threads = max_threads
+        self.max_tasks = max_tasks
+        @threads = Array.new
+        @threads.extend(MonitorMixin)
+        @threads_waiting = 0
+        @tasks = Array.new
+        @tasks.extend(MonitorMixin)
+        @task_enqueued = @tasks.new_cond
+        @task_completed = @tasks.new_cond
+        @cur_tasks = 0
+    end
+    
+    ##
+    # Returns the maximum number of worker threads.
+    # This value is set upon initialization and cannot be changed afterwards.
+    #
+    #  wq = WorkQueue.new()
+    #  wq.max_threads		#=> Infinity
+    #  wq = WorkQueue.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 = WorkQueue.new(10)
+    #  wq.cur_threads		#=> 0
+    #  wq.enqueue_b {}
+    #  wq.cur_threads		#=> 1
+    #
+    def cur_threads
+        @threads.size
+    end
+    
+    ##
+    # Returns the maximum number of queued tasks.
+    # This value is set upon initialization and cannot be changed afterwards.
+    #
+    #  wq = WorkQueue.new()
+    #  wq.max_tasks		#=> Infinity
+    #  wq = WorkQueue.new(nil,1)
+    #  wq.max_tasks		#=> 1
+    #
+    def max_tasks
+        @max_tasks
+    end
+    
+    ##
+    # Returns the current number of active tasks.
+    # This value is just a snapshot, and may change immediately upon returning.
+    #
+    #  wq = WorkQueue.new(1)
+    #  wq.enqueue_b { sleep(1) }
+    #  wq.cur_tasks		#=> 0
+    #  wq.enqueue_b {}
+    #  wq.cur_tasks		#=> 1
+    #
+    def cur_tasks
+        @cur_tasks
+    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 = WorkQueue.new(1)
+    #  wq.enqueue_p(Proc.new {})
+    #
+    def enqueue_p(proc, *args)
+        enqueue(proc, args) 
+    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 = WorkQueue.new(1)
+    #  wq.enqueue_b {}
+    #
+    def enqueue_b(*args, &block)
+       enqueue(block, args) 
+    end
+    
+    ##
+    # Waits until the tasks queue is empty and all worker threads have finished.
+    #
+    #  wq = WorkQueue.new(1)
+    #  wq.enqueue_b { sleep(1) }
+    #  wq.join
+    #
+    def join
+        @tasks.synchronize do
+            @task_completed.wait_while { cur_tasks > 0 }
         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 = timeout(keep_alive) { @tasks.pop }
-        proc.call(*args)
-      rescue Timeout::Error
-        break
-      rescue Exception
-        # suppress exception
-      end
-      break if cur_threads > max_threads
+    
+    ##
+    # Stops all worker threads immediately, aborting any ongoing tasks.
+    #
+    #  wq = WorkQueue.new(1)
+    #  wq.enqueue_b { sleep(1) }
+    #  wq.kill
+    #
+    def kill
+        @threads.dup.each { |thread| thread.exit.join }
+        @threads.clear
+        @threads_waiting = 0
+        @tasks.clear
+        @cur_tasks = 0
     end
-  end
-
+    
+    private
+    
+    ##
+    # Generic
+    #
+    def enqueue(proc, args)
+        @tasks.synchronize do
+            @task_completed.wait_while { cur_tasks >= max_tasks }
+            @tasks << [proc, args]
+            @cur_tasks += 1
+            @task_enqueued.signal
+            spawn_thread
+        end
+    end
+    
+    ##
+    # 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
+    
+    ##
+    # Sets the maximum number of queued tasks.
+    #
+    def max_tasks=(value)
+        raise ArgumentError, "the maximum number of tasks must be positive" if value and value <= 0
+        @max_tasks = value || 1.0/0
+    end
+    
+    ##
+    # Enrolls a new worker thread.
+    # The request is only carried out if necessary.
+    #
+    def spawn_thread
+        @threads.synchronize do
+            if cur_threads < max_threads and @threads_waiting <= 0 and @tasks.size > 0
+                @threads << Thread.new do
+                    begin
+                        work
+                    ensure
+                        @threads.synchronize do
+                            @threads.delete(Thread.current)
+                        end
+                    end
+                end
+            end
+        end
+    end
+    
+    
+    ##
+    # Repeatedly process the tasks queue.
+    #
+    def work
+       loop do 
+            begin
+                proc, args = @tasks.synchronize do
+                    @threads_waiting += 1
+                    @task_enqueued.wait_while { @tasks.size <= 0 }
+                    @threads_waiting -= 1
+                    @tasks.shift
+                end
+                proc.call(*args)
+            rescue Exception => e
+                # Suppress Exception
+            ensure
+                @tasks.synchronize do
+                    @cur_tasks -= 1
+                    @task_completed.broadcast
+                end
+            end
+       end
+    end
+    
 end

data/tasks/test.rake

@@ -10,13 +10,4 @@ namespace(:test) do
     t.warning = true
   end
 
-  desc "Run tests on multiple ruby versions"
-  task(:compatibility) do
-    versions = %w[1.8.6 1.8.7 1.9.1 jruby]
-    system <<-CMD
-  bash -c 'source ~/.rvm/scripts/rvm;
-       rvm #{versions.join(',')} rake test:unit'
-    CMD
-  end
-
 end

data/test/tc_work_queue.rb

@@ -37,6 +37,28 @@ class TC_WorkQueue < Test::Unit::TestCase
     wq.join
     assert_equal(s, "Hello #2")
   end
+  
+  def test_inner_enqueue
+    s = String.new
+    wq = WorkQueue.new
+    wq.enqueue_b do
+      sleep 0.01
+      wq.enqueue_b(s) { |str| str.replace("Hello #1")  }
+      sleep 0.01
+    end
+    wq.join
+    assert_equal(s, "Hello #1")
+  end
+  
+  def test_threads_recycle
+    wq = WorkQueue.new
+    wq.enqueue_b { sleep 0.01 }
+    sleep 0.02
+    assert_equal(wq.cur_threads, 1)
+    wq.enqueue_b { sleep 0.01 }
+    assert_equal(wq.cur_threads, 1)
+    wq.join
+  end
 
   def test_max_threads
     assert_raise(ArgumentError) { WorkQueue.new(0) }
@@ -64,21 +86,10 @@ class TC_WorkQueue < Test::Unit::TestCase
     wq.join
   end
 
-  def test_keep_alive
-    assert_raise(ArgumentError) { WorkQueue.new(nil,nil,0) }
-    assert_raise(ArgumentError) { WorkQueue.new(nil,nil,-1) }
-    wq = WorkQueue.new(1,1,0.01)
-    wq.enqueue_b { sleep(0.01) }
-    assert_equal(wq.cur_threads, 1)
-    sleep(0.1)
-    assert_equal(wq.cur_threads, 0)
-    wq.join
-  end
-
   def test_stress
     a = []
     m = Mutex.new
-    wq = WorkQueue.new(100,200,0.1)
+    wq = WorkQueue.new(100,200)
     (1..1000).each do
       wq.enqueue_b(a,m) { |str,mut|
         sleep(0.01)
@@ -89,4 +100,12 @@ class TC_WorkQueue < Test::Unit::TestCase
     assert_equal(a.size, 1000)
   end
 
+  def test_kill
+    s = String.new
+    wq = WorkQueue.new
+    wq.enqueue_b(s) { |str| sleep 0.1; str.replace("Hello")  }
+    wq.kill
+    assert_equal(s, "")
+  end
+
 end

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: work_queue
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
+  hash: 13
+  prerelease: 
+  segments: 
+  - 2
+  - 0
+  - 1
+  version: 2.0.1
 platform: ruby
 authors: 
 - Miguel Fonseca
@@ -9,8 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-17 00:00:00 +00:00
-default_executable: 
+date: 2011-11-21 00:00:00 Z
 dependencies: []
 
 description: 
@@ -29,7 +34,6 @@ files:
 - tasks/test.rake
 - lib/work_queue.rb
 - test/tc_work_queue.rb
-has_rdoc: true
 homepage: http://github.com/fmmfonseca/work_queue
 licenses: []
 
@@ -42,21 +46,29 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 59
+      segments: 
+      - 1
+      - 8
+      - 6
       version: 1.8.6
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
 summary: A tunable work queue, designed to coordinate work between a producer and a pool of worker threads.