workers 0.0.2 → 0.0.3

data/README.md

@@ -1,7 +1,7 @@
 # Workers
 
 Workers is a Ruby gem for performing work in background threads.
-Design goals include high performance, low latency, simple API, and customizability.
+Design goals include high performance, low latency, simple API, customizability, and multi-layered architecture.
 
 ## Installation
 
@@ -21,7 +21,7 @@ Or install it yourself as:
 
     # Initialize a worker pool.
     pool = Workers::Pool.new
-    
+
     # Perform some work in the background.
     100.times do
       pool.perform do
@@ -29,18 +29,18 @@ Or install it yourself as:
         puts "Hello world from thread #{Thread.current.object_id}"
       end
     end
-    
+
     # Tell the workers to shutdown.
     pool.shutdown do
       puts "Worker thread #{Thread.current.object_id} is shutting down."
     end
-    
-    # Wait for the workers to finish.
+
+    # Wait for the workers to shutdown.
     pool.join
 
 ## Advanced Usage
 
-The Worker class is designed to be customized.
+The Worker class is designed to be customized through inheritence and its event system:
 
     # Create a custom worker class that handles custom commands.
     class CustomWorker < Workers::Worker
@@ -53,32 +53,101 @@ The Worker class is designed to be customized.
         end
       end
     end
-    
+
     # Create a pool that uses your custom worker class.
     pool = Workers::Pool.new(:worker_class => CustomWorker)
-    
+
     # Tell the workers to do some work using custom events.
     100.times do |i|
       pool.enqueue(:my_custom, i)
     end
-    
+
     # Tell the workers to shutdown.
     pool.shutdown do
       puts "Worker thread #{Thread.current.object_id} is shutting down."
     end
-    
-    # Wait for it to finish working and shutdown.
+
+    # Wait for the workers to shutdown.
     pool.join
+
+## Timers
+
+Timers provide a way to execute code in the future:
+
+    # Create a one shot timer that executes in 1.5 seconds.
+    timer = Workers::Timer.new(1.5) do
+      puts 'Hello world'
+    end
     
-## Pool Options
+    # Create a periodic timer that loops infinitely or until 'cancel' is called.
+    timer = Workers::PeriodicTimer.new(1) do
+      puts 'Hello world many times'
+    end
+    sleep 5
+    timer.cancel
+
+Callbacks execute using a Workers::Pool in case they contain blocking operations.
 
-The pool class takes a few options (defaults below):
+## Options (defaults below):
 
     pool = Workers::Pool.new(
       :size => 20,                     # Number of threads to create.
-      :logger => nil                   # Ruby Logger instance.
+      :logger => nil,                  # Ruby Logger instance.
       :worker_class => Workers::Worker # Class of worker to use for this pool.
+    )
+
+    worker = Workers::Worker.new(
+      :logger => nil,                  # Ruby Logger instance.
+      :input_queue => nil              # Ruby Queue used for input events.
+    )
+
+    timer = Workers::Timer.new(1,
+      :logger => nil,                  # Ruby logger instance.
+      :repeat => false,                # Repeat the timer until 'cancel' is called.
+      :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).
+    )
     
+
+## TODO - not yet implemented 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:
+
+    Workers.map([1, 2, 3, 4]) { |i| i * i }
+
 ## Contributing
 
 1. Fork it

data/lib/workers/periodic_timer.rb

@@ -0,0 +1,9 @@
+module Workers
+  class PeriodicTimer < Workers::Timer
+    def initialize(delay, options = {}, &block)
+      options[:repeat] = true
+
+      super(delay, options, &block)
+    end
+  end
+end

data/lib/workers/pool.rb

@@ -20,13 +20,13 @@ module Workers
       return nil
     end
 
-    def perform(options = {}, &block)
+    def perform(&block)
       enqueue(:perform, block)
 
       return nil
     end
 
-    def shutdown(options = {}, &block)
+    def shutdown(&block)
       @size.times { enqueue(:shutdown, block) }
 
       return nil

data/lib/workers/scheduler.rb

@@ -0,0 +1,85 @@
+module Workers
+  class Scheduler
+    def initialize(options = {})
+      @pool = options[:pool] || Workers::Pool.new
+      @schedule = SortedSet.new
+      @mutex = Mutex.new
+      @thread = Thread.new { start_loop }
+    end
+
+    def schedule(timer)
+      @mutex.synchronize do
+        @schedule << timer
+      end
+
+      wakeup
+
+      return nil
+    end
+
+    def unschedule(timer)
+      @mutex.synchronize do
+        @schedule.delete(timer)
+      end
+
+      return true
+    end
+
+    def wakeup
+      @thread.wakeup
+
+      return nil
+    end
+
+    def dispose
+      @mutex.synchronize do
+        @pool.shutdown
+        @pool.join
+        @thread.kill
+      end
+
+      return nil
+    end
+
+    private
+
+    def start_loop
+      while true
+        delay = nil
+
+        @mutex.synchronize do
+          process_overdue
+          delay = next_delay
+        end
+
+        delay ? sleep(delay) : sleep
+      end
+
+      return nil
+    end
+
+    def process_overdue
+      overdue = []
+
+      while @schedule.first && @schedule.first.overdue?
+        overdue << @schedule.first
+        @schedule.delete(@schedule.first)
+      end
+
+      overdue.each do |timer|
+        @pool.perform do
+          timer.fire
+        end
+
+        timer.reset
+        @schedule << timer if timer.repeat
+      end
+
+      return nil
+    end
+
+    def next_delay
+      @schedule.first ? @schedule.first.sec_remaining : nil
+    end
+  end
+end

data/lib/workers/timer.rb

@@ -0,0 +1,58 @@
+module Workers
+  class Timer
+    attr_reader :delay
+    attr_reader :repeat
+
+    def initialize(delay, options = {}, &block)
+      @delay = delay
+      @callback = options[:callback] || block
+      @repeat = options[:repeat] || false
+      @scheduler = options[:scheduler] || Workers.scheduler
+      @logger = options[:logger]
+
+      @mutex = Mutex.new
+
+      reset
+
+      @scheduler.schedule(self)
+    end
+
+    def <=>(other)
+      return sec_remaining <=> other.sec_remaining
+    end
+
+    def sec_remaining
+      @mutex.synchronize do
+        diff = @fire_at.to_f - Time.now.utc.to_f
+
+        return (diff > 0) ? diff : 0
+      end
+    end
+
+    def overdue?
+        return sec_remaining <= 0
+    end
+
+    def fire
+      @mutex.synchronize do
+        @callback.call if @callback
+      end
+
+      return nil
+    end
+
+    def cancel
+      @scheduler.unschedule(self)
+
+      return nil
+    end
+
+    def reset
+      @mutex.synchronize do
+        @fire_at = Time.now.utc + @delay
+      end
+
+      return nil
+    end
+  end
+end

data/lib/workers/version.rb

@@ -1,3 +1,3 @@
 module Workers
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/workers/worker.rb

@@ -15,13 +15,13 @@ module Workers
       return nil
     end
 
-    def perform(options = {}, &block)
+    def perform(&block)
       enqueue(:perform, block)
 
       return nil
     end
 
-    def shutdown(options = {}, &block)
+    def shutdown(&block)
       enqueue(:shutdown, block)
 
       return nil

data/lib/workers.rb

@@ -1,4 +1,5 @@
 require 'thread'
+require 'set'
 
 require 'workers/version'
 require 'workers/helpers'
@@ -6,3 +7,14 @@ require 'workers/worker'
 require 'workers/pool'
 require 'workers/event'
 require 'workers/log_proxy'
+require 'workers/scheduler'
+require 'workers/timer'
+require 'workers/periodic_timer'
+
+module Workers
+  def self.scheduler
+    return @scheduler ||= Workers::Scheduler.new
+  end
+end
+
+Workers.scheduler # Force initialization of default scheduler.

data/workers.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |gem|
   gem.version       = Workers::VERSION
   gem.authors       = ["Chad Remesch"]
   gem.email         = ["chad@remesch.com"]
-  gem.description   = %q{Simple to use Ruby workers for performing work in background threads.}
-  gem.summary       = %q{Simple to use Ruby workers featuring high performance, simple to use API, customizable workers, and thread pooling.}
+  gem.description   = %q{Simple Ruby workers for performing work in background threads.}
+  gem.summary       = %q{Workers is a Ruby gem for performing work in background threads. Design goals include high performance, low latency, simple API, customizability, and multi-layered architecture.}
   gem.homepage      = "https://github.com/chadrem/workers"
 
   gem.files         = `git ls-files`.split($/)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: workers
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,9 +9,9 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-12 00:00:00.000000000 Z
+date: 2013-01-18 00:00:00.000000000 Z
 dependencies: []
-description: Simple to use Ruby workers for performing work in background threads.
+description: Simple Ruby workers for performing work in background threads.
 email:
 - chad@remesch.com
 executables: []
@@ -27,7 +27,10 @@ files:
 - lib/workers/event.rb
 - lib/workers/helpers.rb
 - lib/workers/log_proxy.rb
+- lib/workers/periodic_timer.rb
 - lib/workers/pool.rb
+- lib/workers/scheduler.rb
+- lib/workers/timer.rb
 - lib/workers/version.rb
 - lib/workers/worker.rb
 - workers.gemspec
@@ -54,6 +57,7 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Simple to use Ruby workers featuring high performance, simple to use API,
-  customizable workers, and thread pooling.
+summary: Workers is a Ruby gem for performing work in background threads. Design goals
+  include high performance, low latency, simple API, customizability, and multi-layered
+  architecture.
 test_files: []