workers 0.0.3 → 0.0.4

data/README.md

@@ -17,7 +17,7 @@ Or install it yourself as:
 
     $ gem install workers
 
-## Basic Usage
+## Workers - Basic
 
     # Initialize a worker pool.
     pool = Workers::Pool.new
@@ -38,7 +38,7 @@ Or install it yourself as:
     # Wait for the workers to shutdown.
     pool.join
 
-## Advanced Usage
+## Workers - Advanced
 
 The Worker class is designed to be customized through inheritence and its event system:
 
@@ -70,6 +70,9 @@ The Worker class is designed to be customized through inheritence and its event
     # Wait for the workers to shutdown.
     pool.join
 
+Note that you can use custom workers without a pool.
+This effectively gives you direct access to a single event driven thread.
+
 ## Timers
 
 Timers provide a way to execute code in the future:
@@ -83,10 +86,35 @@ Timers provide a way to execute code in the future:
     timer = Workers::PeriodicTimer.new(1) do
       puts 'Hello world many times'
     end
-    sleep 5
+    
+    # Let the timer print some lines.
+    sleep(5)
+    
+    # Shutdown the timer.
     timer.cancel
 
-Callbacks execute using a Workers::Pool in case they contain blocking operations.
+## Schedulers
+
+Schedulers are what trigger Timers to fire.
+The system has a global default scheduler which should meet most needs (Workers.scheduler).
+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
 
 ## Options (defaults below):
 
@@ -114,6 +142,11 @@ Callbacks execute using a Workers::Pool in case they contain blocking operations
       :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 - not yet implemented features
 

data/lib/workers/pool.rb

@@ -5,8 +5,8 @@ module Workers
     DEFAULT_POOL_SIZE = 20
 
     def initialize(options = {})
-      @size = options[:size] || Workers::Pool::DEFAULT_POOL_SIZE
       @logger = Workers::LogProxy.new(options[:logger])
+      @size = options[:size] || Workers::Pool::DEFAULT_POOL_SIZE
       @worker_class = options[:worker_class] || Workers::Worker
 
       @input_queue = Queue.new

data/lib/workers/scheduler.rb

@@ -1,6 +1,9 @@
 module Workers
   class Scheduler
+    include Workers::Helpers
+
     def initialize(options = {})
+      @logger = Workers::LogProxy.new(options[:logger])
       @pool = options[:pool] || Workers::Pool.new
       @schedule = SortedSet.new
       @mutex = Mutex.new
@@ -41,6 +44,10 @@ module Workers
       return nil
     end
 
+    def alive?
+      return @thread && @thread.alive?
+    end
+
     private
 
     def start_loop

data/lib/workers/timer.rb

@@ -1,14 +1,16 @@
 module Workers
   class Timer
+    include Workers::Helpers
+
     attr_reader :delay
     attr_reader :repeat
 
     def initialize(delay, options = {}, &block)
+      @logger = Workers::LogProxy.new(options[:logger])
       @delay = delay
       @callback = options[:callback] || block
       @repeat = options[:repeat] || false
       @scheduler = options[:scheduler] || Workers.scheduler
-      @logger = options[:logger]
 
       @mutex = Mutex.new
 

data/lib/workers/version.rb

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

data/lib/workers/worker.rb

@@ -28,45 +28,59 @@ module Workers
     end
 
     def join(max_wait = nil)
-      raise "Worker can't join itself!" if @thread == Thread.current
+      raise "Worker can't join itself." if @thread == Thread.current
 
       return true if !@thread.join(max_wait).nil?
 
       @thread.kill and return false
     end
 
+    def alive?
+      return @thread && @thread.alive?
+    end
+
     private
 
     def start_event_loop
       while true
-        event = @input_queue.pop # Blocking.
+        event = @input_queue.pop
 
         case event.command
         when :shutdown
-          try_callback(event.data) do |e|
-            log_error("Worker failed run 'shutdown' callback.", e)
-          end
-          return
+          shutdown_handler(event)
+          return nil
         when :perform
-          try_callback(event.data) do |e|
-            log_error("Worker failed run 'perform' callback.", e)
-          end
+          perform_handler(event)
         else
           process_event(event)
         end
       end
+    rescue Exception => e
+      exception_handler(e)
+    end
+
+    def shutdown_handler(event)
+      try_callback(event.data)
+    end
+
+    def perform_handler(event)
+      try_callback(event.data)
+    end
+
+    def exception_handler(e)
+      puts concat_e('Worker event loop died.', e)
     end
 
     def try_callback(callback, &block)
       begin
         callback.call
       rescue Exception => e
-        block.call(e)
+        block.call(e) if block
       end
     end
 
     def process_event(event)
-      raise 'Subclass and override if you need custom commands.'
+      raise "Unhandled event (#{event.inspect}). Subclass and override if you need custom events."
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: workers
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-18 00:00:00.000000000 Z
+date: 2013-01-19 00:00:00.000000000 Z
 dependencies: []
 description: Simple Ruby workers for performing work in background threads.
 email: