workers 0.0.8 → 0.0.9

data/README.md

@@ -82,15 +82,15 @@ Timers provide a way to execute code in the future:
     timer = Workers::Timer.new(1.5) do
       puts 'Hello world'
     end
-    
+
     # Create a periodic timer that loops infinitely or until 'cancel' is called.
     timer = Workers::PeriodicTimer.new(1) do
       puts 'Hello world many times'
     end
-    
+
     # Let the timer print some lines.
     sleep(5)
-    
+
     # Shutdown the timer.
     timer.cancel
 
@@ -102,21 +102,73 @@ You can create additional or custom ones as necessary:
 
     # Create a workers pool with a larger than default thread count (optional).
     pool = Workers::Pool.new(:size => 100)
-    
+
     # Create a scheduler.
     scheduler = Workers::Scheduler.new(:pool => pool)
-    
+
     # Create a timer that uses the above scheduler.
     timer = Workers::Timer.new(1, :scheduler => scheduler) do
       puts 'Hello world'
     end
-    
+
     # Wait for the timer to fire.
     sleep(5)
-    
+
     # Shutdown the scheduler.
     scheduler.dispose
 
+### Tasks
+
+Tasks and task groups build on top of worker pools.
+They provide a means of parallelizing expensive computations and collecing the results:
+
+    # Create a task group (it contains a pool of workers).
+    group = Workers::TaskGroup.new
+
+    # Add tasks to the group.
+    10.times do |i|
+      10.times do |j|
+        group.add(i, j) do
+          i * j # Last statement executed is the result of the task.
+        end
+      end
+    end
+
+    # Execute the tasks (blocks until the tasks complete).
+    # Returns true if all tasks succeed.  False if any fail.
+    group.run
+
+    # Return an array of all the tasks.
+    group.tasks
+
+    # Return an array of the successful tasks.
+    group.successes
+
+    # Return an array of the failed tasks.
+    group.failures
+
+    # Review the results.
+    group.tasks.each do |t|
+      t.succeeded? # True or false (false if an exception occurred).
+      t.failed?    # True or false (true if an exception occurred).
+      t.args       # Input arguments (the value of i in this example).
+      t.result     # Output value (the result of i * i in this example).
+      t.exception  # The exception if one exists.
+    end
+
+### Parallel Map
+
+Task groups and tasks are the building blocks of parallel map:
+
+    group = Workers::TaskGroup.new
+    group.map([1,2,3,4,5]) { |i| i * i }
+
+The below syntax is equivalent to the above:
+
+    Workers.map([1, 2, 3, 4, 5]) { |i| i * i }
+
+Note that any failures will cause an exception to be raised.
+
 ## Options (defaults below):
 
     pool = Workers::Pool.new(
@@ -136,50 +188,29 @@ You can create additional or custom ones as necessary:
       :scheduler => Workers.scheduler,  # The scheduler that manages execution.
       :callback => nil                  # The proc to execute (provide this or a block, but not both).
     )
-    
+
     timer = Workers::PeriodicTimer.new(1,
       :logger => nil,                   # Ruby logger instance.
       :scheduler => Workers.scheduler,  # The scheduler that manages execution.
       :callback => nil                  # The proc to execute (provide this or a block, but not both).
     )
-    
+
     scheduler = Workers::Scheduler.new(
       :logger => nil,                   # Ruby logger instance.
       :pool => Workers::Pool.new        # The workers pool used to execute timer callbacks.
     )
 
-## TODO - missing features
-
-### Tasks
-
-Tasks and task groups build on top of worker pools.
-They provide a means of parallelizing expensive computations and collecing the results:
-
-    # Create a task group (it contains a pool of workers).
-    group = Workers::TaskGroup.new
-
-    # Add tasks to the group.
-    100.times do |i|
-      group.add(i) do
-        i * i
-      end
-    end
-
-    # Execute the tasks (blocks until the tasks complete).
-    group.run
-
-    # Review the results.
-    group.tasks.each do |t|
-      t.succeeded? # True or false (false if an exception occurred).
-      t.args       # Input arguments (the value of i in this example).
-      t.result     # Output value (the result of i * i in this example).
-      t.exception  # The exception if one exists.
-    end
-
-TaskGroup and Task can then be used to build an easy to use parallel map.
-Care will have to taken regarding global data and the thread safety of data structures:
+    group = Workers::TaskGroup.new(
+      :logger => nil,                   # Ruby logger instance.
+      :pool => Workers::Pool.new        # The workers pool used to execute timer callbacks.
+    )
 
-    Workers.map([1, 2, 3, 4]) { |i| i * i }
+    task = Workers::Task.new(
+      :logger => nil,                   # Ruby logger instance.
+      :perform => proc {},              # Required option.  Block of code to run.
+      :args => [],                      # Array of arguments passed to the 'perform' block.
+      :finished => nil,                 # Callback to execute after attempting to run the task.
+    )
 
 ## Contributing
 

data/lib/workers.rb

@@ -10,6 +10,8 @@ require 'workers/log_proxy'
 require 'workers/scheduler'
 require 'workers/timer'
 require 'workers/periodic_timer'
+require 'workers/task'
+require 'workers/task_group'
 
 module Workers
   def self.pool
@@ -29,6 +31,12 @@ module Workers
     @scheduler.dispose if @scheduler
     @scheduler = val
   end
+
+  def self.map(vals, &block)
+    return Workers::TaskGroup.new.map(vals) do |v|
+      block.call(v)
+    end
+  end
 end
 
 # Force initialization of defaults.

data/lib/workers/task.rb

@@ -0,0 +1,46 @@
+module Workers
+  class Task
+    include Workers::Helpers
+
+    attr_reader :args
+    attr_reader :result
+    attr_reader :exception
+    attr_reader :state
+
+    def initialize(options = {})
+      @logger = Workers::LogProxy.new(options[:logger])
+      @args = options[:args] || []
+      @perform = options[:perform] || raise('Perform callback is required.')
+      @finished = options[:finished]
+      @state = :initialized
+
+      return nil
+    end
+
+    def run
+      raise "Invalid state (#{@state})." unless @state == :initialized
+
+      @state = :running
+
+      begin
+        @result = @perform.call(*@args)
+        @state = :succeeded
+      rescue Exception => e
+        @state = :failed
+        @exception = e
+      end
+
+      @finished.call(self)
+
+      return nil
+    end
+
+    def succeeded?
+      return @state == :succeeded
+    end
+
+    def failed?
+      return @state == :failed
+    end
+  end
+end

data/lib/workers/task_group.rb

@@ -0,0 +1,96 @@
+module Workers
+  class TaskGroup
+    include Workers::Helpers
+
+    attr_reader :state
+    attr_reader :tasks
+
+    def initialize(options = {})
+      @logger = Workers::LogProxy.new(options[:logger])
+      @pool = options[:pool] || Workers.pool
+      @state = :initialized
+      @tasks = []
+      @lock = Mutex.new
+      @finished_count = 0
+      @conditional = ConditionVariable.new
+
+      return nil
+    end
+
+    def add(*args, &block)
+      state!(:initialized)
+
+      if args[0].is_a?(Workers::Task)
+        @tasks << args[0]
+      else
+        @tasks << Workers::Task.new(:args => args, :perform => block, :finished => method(:finished))
+      end
+
+      return nil
+    end
+
+    def run
+      state!(:initialized)
+
+      @state = :running
+      @run_thread = Thread.current
+
+      @lock.synchronize do
+        @tasks.each do |task|
+          @pool.perform { task.run }
+        end
+
+        @conditional.wait(@lock)
+      end
+
+      return @tasks.all? { |t| t.succeeded? }
+    end
+
+    def successes
+      return @tasks.select { |t| t.succeeded? }
+    end
+
+    def failures
+      return @tasks.select { |t| t.failed? }
+    end
+
+    def map(inputs, &block)
+      inputs.each do |input|
+        add(input) do |i|
+          block.call(i)
+        end
+      end
+
+      run
+
+      if (failure = failures[0])
+        a = failure.args.inspect
+        m = failure.exception.message
+        b = failure.exception.backtrace.join("\n")
+
+        raise "At least one task failed. ARGS=#{a}, TRACE=#{m}\n#{b}\n----------\n"
+      end
+
+      return tasks.map { |t| t.result }
+    end
+
+    private
+
+    def state!(*args)
+      unless args.include?(@state)
+        raise "Invalid state (#{@state})."
+      end
+
+      return nil
+    end
+
+    def finished(task)
+      @lock.synchronize do
+        @finished_count += 1
+        @conditional.signal if @finished_count >= @tasks.count
+      end
+
+      return nil
+    end
+  end
+end

data/lib/workers/version.rb

@@ -1,3 +1,3 @@
 module Workers
-  VERSION = '0.0.8'
+  VERSION = '0.0.9'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: workers
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-02 00:00:00.000000000 Z
+date: 2013-05-17 00:00:00.000000000 Z
 dependencies: []
 description: Simple Ruby workers for performing work in background threads.
 email:
@@ -30,6 +30,8 @@ files:
 - lib/workers/periodic_timer.rb
 - lib/workers/pool.rb
 - lib/workers/scheduler.rb
+- lib/workers/task.rb
+- lib/workers/task_group.rb
 - lib/workers/timer.rb
 - lib/workers/version.rb
 - lib/workers/worker.rb