queue_to_the_future 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,19 +1,19 @@
-= queue_to_the_future
+= Queue to the Future!
 
 An easy way to create asynchronous execution paths in an unobtrusive way. Queue to the Future uses a managed pool of workers
 to keep overhead to a minimum.
 
 == Synopsis
-  f = Future(list, of, args) do |list, of, args|
-    sleep(1)
-    "done."
-  end
+  require "queue_to_the_future"
   
   # returns immediately
-  puts f.inspect            #=> #<QueueToTheFuture::Job:0x7ffa641c ... >
+  result = Future("list", "of", "args") do |*args|
+    sleep(1)
+    args.join(" ")
+  end
   
   # blocks until completed
-  puts f                    #=> done.
+  puts result                    #=> "list of args"
 
 == Copyright
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/queue_to_the_future.rb

@@ -5,24 +5,42 @@ require 'queue_to_the_future/worker'
 require 'queue_to_the_future/job'
 
 module QueueToTheFuture
-  @@maximum_workers = 15
-  
+  # The maximum number of workers to create for processing jobs.
+  #
+  # @return [Fixnum] Default is 15
   def self.maximum_workers
-    @@maximum_workers
+    @@maximum_workers ||= 15
   end
   
+  # Setter method for {maximum_workers}
+  #
+  # @param [Fixnum] number Any integer greater than 0
+  # @return [Fixnum] number given
+  # @raise [StandardError] If the number given is less than 1
   def self.maximum_workers=(number)
     raise StandardError.new("Bad workforce size: #{number}. Must be at least 1.") unless (number = number.to_i) >= 1
     @@maximum_workers = number
   end
-  
-  def self.schedule(job)
-    Coordinator.instance.schedule(job)
-  end
 end
 
 module Kernel
+  # Main interface for asynchronous job scheduling. (Where the magick begins)
+  # 
+  # @example
+  #   http        = Net::HTTP.new("ia.media-imdb.com")
+  #   image_path  = "/images/M/MV5BMTkzNDQyMjc0OV5BMl5BanBnXkFtZTcwNDQ4MDYyMQ@@._V1._SX100_SY133_.jpg"
+  #   
+  #   image = Future(image_path) do |path|
+  #     http.request(Net::HTTP::Get.new(path)).body
+  #   end
+  # 
+  #   # do other things
+  #
+  #   puts image.size # => 6636
+  #
+  # @param (see QueueToTheFuture::Job#initialize)
+  # @return [QueueToTheFuture::Job] Your proxy into the future
   def Future(*args, &block)
-    QueueToTheFuture.schedule(QueueToTheFuture::Job.new(*args, &block))
+    QueueToTheFuture::Job.new(*args, &block)
   end
 end

data/lib/queue_to_the_future/coordinator.rb

@@ -1,31 +1,53 @@
 require 'singleton'
 
-module QueueToTheFuture  
+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
     
+    # 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 }
     end
     
+    # The number of jobs waiting to be completed.
+    #
+    # @return [Fixnum] Size of job queue
     def job_count
       synchronize { @job_queue.size }
     end
     
+    # The number of workers being utilized to complete jobs.
+    #
+    # @return [Fixnum] Number of workers
     def workforce_size
       synchronize { @workforce.size }
     end
     
+    # Removes a worker from the workforce.
+    #
+    # @param [QueueToTheFuture::Worker] worker
     def relieve(worker)
       synchronize { @workforce -= [worker] }
     end
     
+    # Append a job to the job queue.
+    #
+    # @param [QueueToTheFuture::Job] job
     def schedule(job)
       synchronize do
         @job_queue.push(job)

data/lib/queue_to_the_future/job.rb

@@ -1,16 +1,30 @@
 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) }
     
+    # Creates a job and schedules it by calling {Coordinator#schedule}.
+    #
+    # @param [List] *args The list of arguments to pass to the given block
+    # @param [Proc] &block The block to be executed
     def initialize(*args, &block)
       @args   = args
       @block  = block
+      Coordinator::instance.schedule(self)
     end
     
+    # Execute the job.
+    #
+    # This is called by the worker the job gets assigned to.
+    # @return [nil]
     def __execute__
-      @result = @block.call(*@args)
+      @result = @block.call(*@args); nil
     end
     
+    # Allows the job to behave as the return value of the block.
+    #
+    # 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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: queue_to_the_future
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Devin Christensen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-12 00:00:00 -07:00
+date: 2010-01-18 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency