workers 0.2.2 → 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4b66f1edc747b5df57e671c9efe7abbd4f36a863
+  data.tar.gz: 16b9fcb187bfda5a629160de3b0c742c66f5f1b4
+SHA512:
+  metadata.gz: 1c4db47993b135c9dfbb6d8feb703ee82946bd67f98a953ef00673e5b83d432426764ab84e2604650b46628c55e11172b76940960024b26a1a6b9cf5a924cb06
+  data.tar.gz: 4d1a0306500a6e26741d0516ae0906b7ad9c9f5fc2e6ab76561174ab73c8dada2a88d683a4d3c2108d90b62b79c0a96e72f7f95716023c1238cea1cf36fd75bd

data/README.md

@@ -104,6 +104,8 @@ This method uses a mutex so you can serialize portions of your tasks that aren't
 
 The main purpose of the Worker class is to add an event system on top of Ruby's built-in Thread class.
 This greatly simplifies inter-thread communication.
+Workers are fairly low level and don't handle exceptions for you.
+Failing to handle exceptions will result in dead workers so you must rescue them in your application code.
 
     # Initialize a worker pool.
     pool = Workers::Pool.new
@@ -111,8 +113,12 @@ This greatly simplifies inter-thread communication.
     # Perform some work in the background.
     100.times do
       pool.perform do
-        sleep(rand(3))
-        puts "Hello world from thread #{Thread.current.object_id}"
+        begin
+          sleep(rand(3))
+          puts "Hello world from thread #{Thread.current.object_id}"
+        rescue Exception => e
+          puts "Oh no, my hello world failed!"
+        end
       end
     end
 
@@ -134,8 +140,12 @@ The Worker class is designed to be customized through inheritence and its event
       def process_event(event)
         case event.command
         when :my_custom
-          puts "Worker received custom event: #{event.data}"
-          sleep(1)
+          begin
+            puts "Worker received custom event: #{event.data}"
+            sleep(1)
+          rescue Exception => e
+            puts "This is a very sad program."
+          end
         end
       end
     end
@@ -156,8 +166,30 @@ 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.
+#### Without pools
+
+In most cases you will be using a group of workers (a pool) as demonstrated above.
+In certain cases, you may want to use a worker directly without the pool.
 This effectively gives you direct access to a single event-driven thread.
+Note that you must handle exceptions yourself since you are working directly with the worker class:
+
+    # Create a single worker.
+    worker = Workers::Worker.new
+    
+    # Perform some work in the background.
+    25.times do |i|
+      worker.perform do
+        begin
+          sleep(0.1)
+          puts "Hello world from thread #{Thread.current.object_id}"
+        rescue Exception => e
+          puts "Oh no, my hello world failed!"
+        end
+      end
+    end
+    
+    # Tell the worker to shutdown.
+    worker.shutdown
 
 #### Options
 
@@ -197,7 +229,8 @@ Pools can be adjusted using the below methods:
 
 ## Timers
 
-Timers provide a way to execute code in the future:
+Timers provide a way to execute code in the future.
+You can easily use them to tell a Worker or it's higher level classes (Task, TaskGroup, etc) to perform work in the future.
 
     # Create a one shot timer that executes in 1.5 seconds.
     timer = Workers::Timer.new(1.5) do
@@ -261,6 +294,41 @@ You can create additional schedulers as necessary:
       :pool => Workers::Pool.new        # The workers pool used to execute timer callbacks.
     )
 
+## Concurrency and performance
+
+Workers is tested with both JRuby and MRI (C Ruby).
+Below are some notes specific to each Ruby implementation.
+In summary, JRuby is the recommended Ruby to use with Workers since it provides the highest performance with multiple CPU cores.
+
+#### JRuby (recommended)
+
+JRuby is designed for multi-threaded apps running on multiple cores.
+When used with Workers, you will be able to saturate all of your CPU cores with little to no tuning.
+It is highly recommended you increase the number of workers in your pool if you have a large number of cores.
+A good starting point is 1x - 2x the number of cores for CPU bound apps.
+For IO bound apps you will need to do some benchmarking to figure out what is best for you.
+A good starting point is 4x - 10x the number of cores for IO bound apps.
+
+#### MRI 1.9.x or newer (supported)
+
+MRI 1.9 and above use real operating system threads with a global interpreter lock (GIL).
+The bad news is that due to the GIL, only one thread can execute Ruby code at a given point in time.
+This means your app will be CPU bound to a single core.
+The good news is that IO bound applications will still see huge benefits from Workers.
+Examples of such IO are web service requests, web servers, web crawlers, database queries, writing to disk, etc.
+Threads performing such IO will temporarily release the GIL and thus let another thread execute Ruby code.
+
+#### MRI 1.8.x or older (not supported)
+
+These old versions of Ruby used green threads (application layer threads) instead of operating system level threads.
+I recommend you upgrade to a newer version as I haven't tested Workers with them.
+They also aren't officially supported by the Ruby community at this point.
+
+#### Rubinius
+
+I haven't tested Workers with Rubinius, but in theory it should just work.
+The above JRuby notes should apply.
+
 ## Contributing
 
 1. Fork it

data/lib/workers.rb

@@ -9,6 +9,7 @@ require 'workers/pool'
 require 'workers/event'
 require 'workers/log_proxy'
 require 'workers/scheduler'
+require 'workers/bucket_scheduler'
 require 'workers/timer'
 require 'workers/periodic_timer'
 require 'workers/task'
@@ -16,30 +17,41 @@ require 'workers/task_group'
 
 module Workers
   def self.pool
-    return @pool ||= Workers::Pool.new
+    lock do
+      return @pool ||= Workers::Pool.new
+    end
   end
 
   def self.pool=(val)
-    @pool.dispose if @pool
-    @pool = val
+    lock do
+      @pool.dispose if @pool
+      @pool = val
+    end
   end
 
   def self.scheduler
-    return @scheduler ||= Workers::Scheduler.new
+    lock do
+      return @scheduler ||= Workers::Scheduler.new
+    end
   end
 
   def self.scheduler=(val)
-    @scheduler.dispose if @scheduler
-    @scheduler = val
+    lock do
+      @scheduler.dispose if @scheduler
+      @scheduler = val
+    end
   end
 
   def self.map(inputs, options = {}, &block)
     return Workers::TaskGroup.new.map(inputs, options) do |i|
-      block.call(i)
+      yield(i)
     end
   end
+
+  def self.lock(&block)
+    (@lock ||= Monitor.new).synchronize { yield if block_given? }
+  end
 end
 
 # Force initialization of defaults.
-Workers.pool
-Workers.scheduler
+Workers.lock

data/lib/workers/bucket_scheduler.rb

@@ -0,0 +1,46 @@
+module Workers
+  class BucketScheduler
+    DEFAULT_BUCKET_SIZE = 100
+    DEFAULT_POOL_SIZE = 1
+
+    def initialize(options = {})
+      options[:bucket_size] ||= DEFAULT_BUCKET_SIZE
+      options[:pool_size] ||=  DEFAULT_POOL_SIZE
+
+      @logger = Workers::LogProxy.new(options[:logger])
+      @options = options
+
+      @schedulers = (0...(options[:bucket_size])).map {
+        Workers::Scheduler.new(:pool => Workers::Pool.new(:logger => @logger, :size => options[:pool_size]))
+      }
+    end
+
+    def schedule(timer)
+      @schedulers[timer.hash % @options[:bucket_size]].schedule(timer)
+
+      return nil
+    end
+
+    def unschedule(timer)
+      @schedulers[timer.hash % @options[:bucket_size]].unschedule(timer)
+
+      return nil
+    end
+
+    def wakeup
+      @schedulers.each { |s| s.wakeup }
+
+      return nil
+    end
+
+    def dispose
+      @schedulers.each { |s| s.dispose }
+
+      return nil
+    end
+
+    def alive?
+      return @schedulers.all? { |s| s.alive? }
+    end
+  end
+end

data/lib/workers/scheduler.rb

@@ -4,7 +4,7 @@ module Workers
 
     def initialize(options = {})
       @logger = Workers::LogProxy.new(options[:logger])
-      @pool = options[:pool] || Workers.pool
+      @pool = options[:pool] || Workers::Pool.new
       @schedule = SortedSet.new
       @mutex = Mutex.new
       @thread = Thread.new { start_loop }
@@ -27,7 +27,7 @@ module Workers
         @schedule.delete(timer)
       end
 
-      return true
+      return nil
     end
 
     def wakeup

data/lib/workers/version.rb

@@ -1,3 +1,3 @@
 module Workers
-  VERSION = '0.2.2'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workers
 version: !ruby/object:Gem::Version
-  version: 0.2.2
-  prerelease: 
+  version: 0.3.0
 platform: ruby
 authors:
 - Chad Remesch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-03 00:00:00.000000000 Z
+date: 2015-02-23 00:00:00.000000000 Z
 dependencies: []
 description: Workers is a Ruby gem for performing work in background threads.
 email:
@@ -18,12 +17,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/workers.rb
+- lib/workers/bucket_scheduler.rb
 - lib/workers/event.rb
 - lib/workers/helpers.rb
 - lib/workers/log_proxy.rb
@@ -38,27 +38,26 @@ files:
 - workers.gemspec
 homepage: https://github.com/chadrem/workers
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.4.5
 signing_key: 
-specification_version: 3
+specification_version: 4
 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. It provides a number of simple to use classes that solve a wide range