queue_to_the_future 0.1.1 → 0.2.1

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Devin Christensen
+Copyright (c) 2009-2010 Devin Christensen
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -17,4 +17,4 @@ to keep overhead to a minimum.
 
 == Copyright
 
-Copyright (c) 2010 Devin Christensen. See LICENSE for details.
+Copyright (c) 2009-2010 Devin Christensen. See LICENSE for details.

data/Rakefile

@@ -37,7 +37,9 @@ task :default => :spec
 
 begin
   require 'yard'
-  YARD::Rake::YardocTask.new
+  YARD::Rake::YardocTask.new do |t|
+    t.options = ["--files", "LICENSE"]
+  end
 rescue LoadError
   task :yardoc do
     abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.1

data/lib/queue_to_the_future.rb

@@ -1,10 +1,16 @@
 require 'thread'
+require 'mutex_m'
+require 'singleton'
 
 require 'queue_to_the_future/coordinator'
-require 'queue_to_the_future/worker'
 require 'queue_to_the_future/job'
 
 module QueueToTheFuture
+  # Returns the current version of QueueToTheFuture
+  def self.VERSION
+    @@version ||= open(File.join(File.dirname(__FILE__), '..', 'VERSION')).read.strip
+  end
+  
   # The maximum number of workers to create for processing jobs.
   #
   # @return [Fixnum] Default is 15

data/lib/queue_to_the_future/coordinator.rb

@@ -1,68 +1,78 @@
-require 'singleton'
-
 module QueueToTheFuture
+  
   # The coordinator schedules jobs and maintains the workforce size to match. As jobs
   # get added the coordinator creates workers to complete them. The number of
   # workers created will never exceed {QueueToTheFuture::maximum_workers}.
   class Coordinator
     include Singleton
     
+    # Convenience class level methods that proxy to the singleton instance
+    %w/schedule queue_length workforce_size shutdown/.each do |meth|
+      instance_eval("def #{meth}(*args); instance.#{meth}(*args); end")
+    end
+    
     # Creates the coordinator.
     # 
     # Note: This is a singleton class. To access the instance use 
     # {http://ruby-doc.org/stdlib/libdoc/singleton/rdoc/index.html Coordinator::instance}.
     def initialize
-      @job_queue  = []
-      @workforce  = []
-      @lock       = Mutex.new
-    end
-    
-    # The next scheduled job.
-    #
-    # @return [QueueToTheFuture::Job] Next job
-    def next_job
-      synchronize { @job_queue.shift }
+      @job_queue = Queue.new
+      @workforce = []
+      
+      @workforce.extend(Mutex_m)
     end
     
-    # The number of jobs waiting to be completed.
+    # The current length of the job queue
     #
-    # @return [Fixnum] Size of job queue
-    def job_count
-      synchronize { @job_queue.size }
+    # @return [Fixnum] Length of job queue
+    def queue_length
+      @job_queue.length
     end
     
     # The number of workers being utilized to complete jobs.
     #
     # @return [Fixnum] Number of workers
     def workforce_size
-      synchronize { @workforce.size }
+      @workforce.size
     end
     
-    # Removes a worker from the workforce.
+    # Append a QueueToTheFuture::Job to the queue.
     #
-    # @param [QueueToTheFuture::Worker] worker
-    def relieve(worker)
-      synchronize { @workforce -= [worker] }
-    end
-    
-    # Append a job to the job queue.
+    # If there are workers available, the first available worker will be
+    # woken up to perform the QueueToTheFuture::Job. If there are no
+    # available workers, one will be created as long as doing so will
+    # not cause the workforce to exceed QueueToTheFuture::maximum_workers.
     #
     # @param [QueueToTheFuture::Job] job
     def schedule(job)
-      synchronize do
-        @job_queue.push(job)
-        
-        if @workforce.size < QueueToTheFuture.maximum_workers && @workforce.size < @job_queue.size
-          @workforce.push Worker.new(@workforce.size)
-        end
+      
+      # If we can't get a lock on the @workforce then the Coordinator is most likely shutting down.
+      # We want to skip creating new workers in this case.
+      if @job_queue.num_waiting == 0 && @workforce.size < QueueToTheFuture.maximum_workers && @workforce.mu_try_lock
+        @workforce.push Thread.new() { while job = @job_queue.shift; job.__execute__; end }
+        @workforce.mu_unlock
       end
       
-      job
+      @job_queue.push(job)
+      
+      nil
     end
     
-    private
-    def synchronize(&block)
-      @lock.synchronize(&block)
+    # Prevents more workers from being created and waits for all jobs
+    # to finish. Once the jobs have completed the workers are terminated.
+    #
+    # To start up again just QueueToTheFuture::schedule more jobs once
+    # this method returns.
+    #
+    # @param [true, false] force If set to true, shutdown immediately
+    #   and clear the queue without waiting for any jobs to complete.
+    def shutdown(force = false)
+      @workforce.mu_synchronize do
+        Thread.pass until @job_queue.empty? unless force
+        while worker = @workforce.shift; worker.terminate; end
+      end
+      
+      nil
     end
   end
-end
+end

data/lib/queue_to_the_future/job.rb

@@ -1,7 +1,7 @@
 module QueueToTheFuture
   # A proxy object for the future return value of a block.
   class Job
-    (instance_methods - %w[__send__ __id__ object_id inspect]).each { |meth| undef_method(meth) }
+    instance_methods.each { |meth| undef_method(meth) unless %w(__send__ __id__ object_id inspect).include?(meth.to_s) }
     
     # Creates a job and schedules it by calling {Coordinator#schedule}.
     #
@@ -10,7 +10,8 @@ module QueueToTheFuture
     def initialize(*args, &block)
       @args   = args
       @block  = block
-      Coordinator::instance.schedule(self)
+      
+      Coordinator.schedule(self)
     end
     
     # Execute the job.
@@ -18,7 +19,12 @@ module QueueToTheFuture
     # This is called by the worker the job gets assigned to.
     # @return [nil]
     def __execute__
-      @result = @block.call(*@args); nil
+      @result = @block[*@args]
+    rescue Exception => e
+      @result = e
+    ensure
+      # Prevent multiple executions
+      def self.__execute__; nil; end
     end
     
     # Allows the job to behave as the return value of the block.
@@ -26,8 +32,16 @@ module QueueToTheFuture
     # Accessing any method on the job will cause code to block
     # until the job is completed.
     def method_missing(*args, &block)
-      Thread.pass while !defined?(@result)
-      @result.send(*args, &block)
+      Thread.pass until defined?(@result)
+      
+      case @result
+      when Exception
+        def self.method_missing(*args, &block); raise @result; end
+      else
+        def self.method_missing(*args, &block); @result.send(*args, &block); end
+      end
+      
+      self.method_missing(*args, &block)
     end
   end
 end

data/spec/queue_to_the_future/coordinator_spec.rb

@@ -0,0 +1,43 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+module QueueToTheFuture
+  describe "Coordinator" do
+    before(:each) do
+      QueueToTheFuture.maximum_workers = 15
+      Coordinator.shutdown
+    end
+    
+    it "should return the length of the job queue" do
+      QueueToTheFuture.maximum_workers = 1
+      Job.new() { sleep(0.1) }
+      
+      5.times do |i|
+        Coordinator.queue_length.should == i
+        Job.new() { sleep(0.1) }
+        Coordinator.queue_length.should == i + 1
+      end
+    end
+    
+    it "should create up to the maximum allowed workers" do
+      (QueueToTheFuture.maximum_workers + 10).times do
+        Job.new { sleep(0.1) }
+      end
+      
+      Coordinator.queue_length.should > 0
+      Coordinator.workforce_size.should == QueueToTheFuture.maximum_workers
+    end
+    
+    it "should shutdown gracefully" do
+      5.times { Job.new { sleep(1) } }
+      
+      Coordinator.workforce_size.should == 5
+      Coordinator.shutdown
+      Coordinator.workforce_size.should == 0
+    end
+    
+    it "should allow shutdown to be forced" do
+      5.times { Job.new { Thread.stop } }
+      Coordinator.shutdown(true)
+    end
+  end
+end

data/spec/queue_to_the_future/job_spec.rb

@@ -0,0 +1,30 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+module QueueToTheFuture
+  describe "Job" do
+    it "should return immediately" do
+      Benchmark.realtime() do
+        j = Job.new { sleep(0.1); "value" }
+      end.should be_close(0, 0.001)
+    end
+    
+    it "should block until completed on access" do
+      Benchmark.realtime() do
+        j = Job.new { sleep(0.1); "blargh" }
+        j.should == "blargh"
+      end.should be_close(0.1, 0.001)
+    end
+    
+    it "should pass all arguments to the block" do
+      j = Job.new(1,2,3) { |*args| args.join(",") }
+      j.should == "1,2,3"
+    end
+    
+    it "should handle exceptions" do
+      j = nil
+      
+      lambda { j = Job.new { raise StandardError.new("Mock Exception") } }.should_not raise_exception()
+      lambda { j.to_s }.should raise_exception(StandardError, "Mock Exception")
+    end
+  end
+end

data/spec/queue_to_the_future_spec.rb

@@ -1,18 +1,20 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 describe "QueueToTheFuture" do
-  it "should work" do
-    start = Time.now.to_f
-    
-    f = Future(1, 2, 3) do |*args|
-      sleep(0.1); args
-    end
-    
-    QueueToTheFuture::Coordinator.instance.workforce_size.should be(1)
-    f.inspect.should match(/^#<QueueToTheFuture::Job/)
-    f.should eql([1,2,3])
-    (Time.now.to_f - start).should be_close(0.1, 0.001)
-    Thread.pass
-    QueueToTheFuture::Coordinator.instance.workforce_size.should be(0)
+  it "should allow the workforce size to be modified" do
+    lambda { QueueToTheFuture.maximum_workers = 20 }.should_not raise_exception()
+  end
+  
+  it "should not accept a workforce size less than 1" do
+    lambda { QueueToTheFuture.maximum_workers = 0 }.should raise_exception(StandardError, /Bad workforce size/)
+  end
+  
+  it "should provide the version being used" do
+    QueueToTheFuture.VERSION.should match(/\d+\.\d+\.\d+/)
+  end
+  
+  it "should provide a Kernel level API for job creation" do
+    f = Future() { sleep(0.1); "blargh" }
+    f.inspect.should match(/QueueToTheFuture::Job/)
   end
 end

data/spec/spec_helper.rb

@@ -3,6 +3,7 @@ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'queue_to_the_future'
 require 'spec'
 require 'spec/autorun'
+require 'benchmark'
 
 Spec::Runner.configure do |config|
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: queue_to_the_future
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Devin Christensen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-18 00:00:00 -07:00
+date: 2010-03-07 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -51,7 +51,8 @@ files:
 - lib/queue_to_the_future.rb
 - lib/queue_to_the_future/coordinator.rb
 - lib/queue_to_the_future/job.rb
-- lib/queue_to_the_future/worker.rb
+- spec/queue_to_the_future/coordinator_spec.rb
+- spec/queue_to_the_future/job_spec.rb
 - spec/queue_to_the_future_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -84,5 +85,7 @@ signing_key:
 specification_version: 3
 summary: Futures for Ruby.
 test_files: 
+- spec/queue_to_the_future/coordinator_spec.rb
+- spec/queue_to_the_future/job_spec.rb
 - spec/queue_to_the_future_spec.rb
 - spec/spec_helper.rb

data/lib/queue_to_the_future/worker.rb

@@ -1,20 +0,0 @@
-module QueueToTheFuture
-  class Worker
-    def initialize(index)
-      @index        = index
-      @coordinator  = Coordinator.instance
-      dispatch
-    end
-    
-    def dispatch
-      Thread.new(@index) do |index|
-        while index < QueueToTheFuture.maximum_workers && (work = @coordinator.next_job)
-          work.__execute__
-          Thread.pass()
-        end
-        
-        @coordinator.relieve(self)
-      end
-    end
-  end
-end