work_queue 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,4 +1,6 @@
-Conceptually, a work queue is designed to coordinate work between a producer and a set of worker threads.
+= 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.
 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.
@@ -8,4 +10,18 @@ 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;
+* To bound resource use, by setting a limit on the maximum number of simultaneously executing threads;
+
+= Usage
+
+Install the gem:
+
+  gem install work_queue
+
+Run the code:
+
+  require 'rubygems'
+  require 'work_queue'
+  wq = WorkQueue.new
+  wq.enqueue_b { puts "Hello from the WorkQueue" }
+  wq.join

data/lib/work_queue.rb

@@ -6,7 +6,7 @@
 # This file contains an implementation of a work queue structure.
 #
 # == Version
-# 0.1.0
+# 0.1.1
 #
 # == Author
 # Miguel Fonseca <fmmfonseca@gmail.com>
@@ -25,19 +25,19 @@ require 'timeout'
 # = WorkQueue
 #
 # == Description
-# A tunable work queue, designed to coordinate work between a producer and a set of worker threads.
+# A tunable work queue, designed to coordinate work between a producer and a pool of worker threads.
 #
 # == Usage
-#  wq = WorkQueue.new(1)
+#  wq = WorkQueue.new
 #  wq.enqueue_b { puts "Hello from the WorkQueue" }
 #  wq.join
 #
 class WorkQueue
 	
-	VERSION = "0.1.0"
+	VERSION = "0.1.1"
 	
 	##
-	# Creates a new work queue.
+	# Creates a new work queue with the desired parameters.
 	#	
 	#  wq = WorkQueue.new(5,10,20)
 	#
@@ -57,6 +57,8 @@ class WorkQueue
 	# 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
 	#
@@ -81,6 +83,8 @@ class WorkQueue
 	# 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
 	#
@@ -116,7 +120,7 @@ class WorkQueue
 	end
 	
 	##
-	# Schedules the given Proc for execution by a worker thread.
+	# 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)
@@ -129,7 +133,7 @@ class WorkQueue
 	end
 	
 	##
-	# Schedules the given Block for execution by a worker thread.
+	# 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)
@@ -142,7 +146,7 @@ class WorkQueue
 	end
 	
 	##
-	# Waits until the tasks queue is empty.
+	# Waits until the tasks queue is empty and all worker threads have finished.
 	#
 	#  wq = WorkQueue.new(1)
 	#  wq.enqueue_b { sleep(1) }
@@ -194,10 +198,11 @@ class WorkQueue
 	end
 	
 	##
-	# Spawns a new worker thread.
+	# 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
+		if cur_threads < max_threads and @tasks.num_waiting <= 0 and cur_tasks > 0
 			@threads_lock.synchronize { 
 				@threads << Thread.new do
 					begin
@@ -211,7 +216,8 @@ class WorkQueue
 	end
 	
 	##
-	# Dismisses an existing worker thread.
+	# 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

data/tasks/gem.rake

@@ -7,7 +7,7 @@ CLEAN.include("pkg")
 spec = Gem::Specification.new do |s|
 	s.name = "work_queue"
 	s.version = WorkQueue::VERSION
-	s.summary = "A tunable work queue, designed to coordinate work between a producer and a set of worker threads."
+	s.summary = "A tunable work queue, designed to coordinate work between a producer and a pool of worker threads."
 	s.homepage = "http://github.com/fmmfonseca/work_queue"
 	s.author = "Miguel Fonseca"
 	s.email = "fmmfonseca@gmail.com"
@@ -16,8 +16,8 @@ spec = Gem::Specification.new do |s|
 	s.files = FileList["LICENSE", "Rakefile", "README.rdoc", "tasks/*.rake", "lib/**/*.rb", "test/tc_*.rb"].to_a
 	s.test_files = Dir.glob("test/tc_*.rb")
 	s.has_rdoc = true
-	s.extra_rdoc_files = ["README.rdoc"]
-	s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "WorkQueue", "--main", "README.rdoc"]
+	s.extra_rdoc_files = %w[README.rdoc]
+	s.rdoc_options = %w[--line-numbers --inline-source --title WorkQueue --main README.rdoc]
 end
 
 # For a list of all attributes refer to http://rake.rubyforge.org/classes/Rake/PackageTask.html

data/tasks/rdoc.rake

@@ -4,6 +4,7 @@ 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 = "WorkQueue"
 	rd.main = "README.rdoc"
 	rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
 	rd.rdoc_dir = "doc"

data/test/tc_work_queue.rb

@@ -28,11 +28,11 @@ class TC_WorkQueue < Test::Unit::TestCase
 	def test_enqueue
 		s = String.new
 		wq = WorkQueue.new
-		# Using Proc
+		# using proc
 		wq.enqueue_p(Proc.new { |str| str.replace("Hello #1") }, s)
 		wq.join
 		assert_equal(s, "Hello #1")
-		# Using Block
+		# using block
 		wq.enqueue_b(s) { |str| str.replace("Hello #2") }
 		wq.join
 		assert_equal(s, "Hello #2")
@@ -78,10 +78,13 @@ class TC_WorkQueue < Test::Unit::TestCase
 	def test_stress
 		a = []
 		m = Mutex.new
-		wq = WorkQueue.new(100)
-		(1..1000).each {
-			wq.enqueue_b(a,m) { |str,mut| sleep(0.01); mut.synchronize { a.push nil } }
-		}
+		wq = WorkQueue.new(100,200,0.1)
+		(1..1000).each do
+			wq.enqueue_b(a,m) { |str,mut| 
+				sleep(0.01)
+				mut.synchronize { a.push nil }
+			}
+		end
 		wq.join
 		assert_equal(a.size, 1000)
 	end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: work_queue
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Miguel Fonseca
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-22 00:00:00 +00:00
+date: 2009-11-24 00:00:00 +00:00
 default_executable: 
 dependencies: []
 
@@ -62,6 +62,6 @@ rubyforge_project:
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: A tunable work queue, designed to coordinate work between a producer and a set of worker threads.
+summary: A tunable work queue, designed to coordinate work between a producer and a pool of worker threads.
 test_files: 
 - test/tc_work_queue.rb