workers 0.0.4 → 0.0.5

data/README.md

@@ -116,35 +116,109 @@ You can create additional or custom ones as necessary:
     # Shutdown the scheduler.
     scheduler.dispose
 
+## Actors
+
+Actors are light weight concurrent objects that use asynchronous message passing to communicate with each other.
+They are event driven and use a worker pool in order to execute their event loop.
+
+    # Create your custom actor class.
+    class MyActor < Workers::Actor
+      private
+      def initialize(options = {})
+        super
+      end
+      
+      def process_event(event)
+       case event.command
+       when :my_custom
+         my_custom_handler(event)
+       end
+      end
+      
+      def my_custom_handler(event)
+        puts "Received a custom event (#{event.inspect})"
+      end
+      
+      def exception_handler(e)
+        puts concat_e("MyActor (#{identifier}) died.", e)
+      end
+      
+      def shutdown_handler(event)
+        puts "MyActor (#{identifier}) is shutting down.  Put cleanup code here."
+      end
+    end
+    
+    # Create some named actors.
+    100.times do |i|
+      MyActor.new(:name => "my_actor_#{i}")
+    end
+    
+    # Send an event to each actors.  Find each actor using the registry.
+    100.times do |i|
+      actor = Workers.registry["my_actor_#{i}"]
+      actor.enqueue(:my_custom, 'hello world')
+    end
+    
+    # Shutdown the actors.
+    100.times do |i|
+      actor = Workers.registry["my_actor_#{i}"]
+      actor.enqueue(:shutdown)
+    end
+
+### Implementation notes
+Because actors use a shared worker pool, it is important that they don't block for long periods of time.
+If you need an actor that can block for long periods then you should give the actor a dedicated thread (:dedicated => true).
+
+## Registries
+
+Registries hold references to named actors.
+In general you shouldn't have to create your own since there is a global one (Workers.registry).
+
 ## Options (defaults below):
 
     pool = Workers::Pool.new(
-      :size => 20,                     # Number of threads to create.
-      :logger => nil,                  # Ruby Logger instance.
-      :worker_class => Workers::Worker # Class of worker to use for this pool.
+      :size => 20,                      # Number of threads to create.
+      :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.
+      :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).
+      :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).
+      :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.
+      :logger => nil,                   # Ruby logger instance.
+      :pool => Workers::Pool.new        # The workers pool used to execute timer callbacks.
+    )
+    
+    actor = Workers::Actor.new(
+      :logger => nil,                   # Ruby logger instance.
+      :dedicated => false,              # If true, the actor runs with a worker pool that has one thread.
+      :pool => Workers.pool,            # The workers pool used to execute events.
+      :mailbox => Workers::Mailbox.new, # The mailbox used to receive events.
+      :registry => Workers.registry,    # The registry used to store a reference to the actor if it has a name.
+      :name => nil                      # The name of the actor (must be unique in the registry).
+    )
+    
+    actor = Workers::DedicatedActor.new(
+      :logger => nil,                   # Ruby logger instance.
+      :mailbox => Workers::Mailbox.new, # The mailbox used to receive events.
+      :registry => Workers.registry,    # The registry used to store a reference to the actor if it has a name.
+      :name => nil                      # The name of the actor (must be unique in the registry).
     )
     
 

data/lib/workers/actor.rb

@@ -0,0 +1,79 @@
+module Workers
+  class Actor
+    include Workers::Helpers
+
+    def initialize(options = {})
+      @logger = Workers::LogProxy.new(options[:logger])
+      @dedicated = options[:dedicated] || false
+      @mailbox = options[:mailbox] || Workers::Mailbox.new
+      @registry = options[:registry] || Workers.registry
+      @name = options[:name]
+      @pool = @dedicated ? Workers::Pool.new(:size => 1) : (options[:pool] || Workers.pool)
+      @alive = true
+
+      @registry.register(self)
+    end
+
+    def enqueue(command, data = nil)
+      return false unless @alive
+
+      @mailbox.push(Event.new(command, data))
+
+      @pool.perform do
+        process_events
+      end
+
+      return true
+    end
+
+    def alive?
+      @mailbox.synchronize do
+        return @alive
+      end
+    end
+
+    def name
+      return @name
+    end
+
+    def identifier
+      return @name ? "#{object_id}:#{@name}" : object_id
+    end
+
+    private
+
+    def process_events
+      while (event = @mailbox.shift)
+        case event.command
+        when :shutdown
+          shutdown_handler(event)
+          @pool.shutdown if @dedicated
+          @mailbox.synchronize do
+            @alive = false
+          end
+        else
+          process_event(event)
+        end
+      end
+    rescue Exception => e
+      @alive = false
+      exception_handler(e)
+    end
+
+    #
+    # Subclass and override the below methods.
+    #
+
+    def process_event(event)
+      puts "Actor (#{identifier}) received event (#{event.inspect})."
+    end
+
+    def exception_handler(e)
+      puts concat_e("Actor (#{identifier}) died.", e)
+    end
+
+    def shutdown_handler(event)
+      puts "Actor (#{identifier}) is shutting down."
+    end
+  end
+end

data/lib/workers/dedicated_actor.rb

@@ -0,0 +1,9 @@
+module Workers
+  class DedicatedActor < Workers::Actor
+    def initialize(options = {})
+      options[:dedicated] = true
+
+      super(options)
+    end
+  end
+end

data/lib/workers/mailbox.rb

@@ -0,0 +1,26 @@
+module Workers
+  class Mailbox
+    def initialize(options = {})
+      @messages = []
+      @mutex = Mutex.new
+    end
+
+    def push(event)
+      @mutex.synchronize do
+        @messages.push(event)
+      end
+    end
+
+    def shift
+      @mutex.synchronize do
+        @messages.shift
+      end
+    end
+
+    def synchronize(&block)
+      @mutex.synchronize do
+        block.call
+      end
+    end
+  end
+end

data/lib/workers/pool.rb

@@ -14,7 +14,7 @@ module Workers
       @size.times { @workers << @worker_class.new(:input_queue => @input_queue) }
     end
 
-    def enqueue(command, data)
+    def enqueue(command, data = nil)
       @input_queue.push(Event.new(command, data))
 
       return nil
@@ -35,5 +35,12 @@ module Workers
     def join(max_wait = nil)
       return @workers.map { |w| w.join(max_wait) }
     end
+
+    def dispose
+      shutdown
+      join
+
+      return nil
+    end
   end
 end

data/lib/workers/registry.rb

@@ -0,0 +1,45 @@
+module Workers
+  class Registry
+    def initialize
+      @mutex = Mutex.new
+      @actors_by_name = {}
+    end
+
+    def register(actor)
+      @mutex.synchronize do
+        return false unless actor.name
+
+        if @actors_by_name[actor.name]
+          raise "Actor already exists (#{actor.name})."
+        else
+          @actors_by_name[actor.name] = actor
+        end
+
+        return true
+      end
+    end
+
+    def unregister(actor)
+      @mutex.synchronize do
+        return false unless actor.name
+        return false unless @actors_by_name[actor.name]
+
+        @actors_by_name.delete(actor.name)
+
+        return true
+      end
+    end
+
+    def [](val)
+      @mutex.synchronize do
+        return @actors_by_name[val]
+      end
+    end
+
+    def dispose
+      @mutex.synchronize do
+        @actors_by_name.clear
+      end
+    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.new
+      @pool = options[:pool] || Workers.pool
       @schedule = SortedSet.new
       @mutex = Mutex.new
       @thread = Thread.new { start_loop }

data/lib/workers/version.rb

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

data/lib/workers/worker.rb

@@ -9,7 +9,7 @@ module Workers
       @thread = Thread.new { start_event_loop }
     end
 
-    def enqueue(command, data)
+    def enqueue(command, data = nil)
       @input_queue.push(Event.new(command, data))
 
       return nil

data/lib/workers.rb

@@ -10,11 +10,41 @@ require 'workers/log_proxy'
 require 'workers/scheduler'
 require 'workers/timer'
 require 'workers/periodic_timer'
+require 'workers/mailbox'
+require 'workers/actor'
+require 'workers/dedicated_actor'
+require 'workers/registry'
 
 module Workers
+  def self.pool
+    return @pool ||= Workers::Pool.new
+  end
+
+  def self.pool=(val)
+    @pool.dispose if @pool
+    @pool = val
+  end
+
   def self.scheduler
     return @scheduler ||= Workers::Scheduler.new
   end
+
+  def self.scheduler=(val)
+    @scheduler.dispose if @scheduler
+    @scheduler = val
+  end
+
+  def self.registry
+    return @registry ||= Workers::Registry.new
+  end
+
+  def self.registry=(val)
+    @registry.dispose if @registry
+    @registry = val
+  end
 end
 
-Workers.scheduler # Force initialization of default scheduler.
+# Force initialization of defaults.
+Workers.pool
+Workers.scheduler
+Workers.registry

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: workers
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -24,11 +24,15 @@ files:
 - README.md
 - Rakefile
 - lib/workers.rb
+- lib/workers/actor.rb
+- lib/workers/dedicated_actor.rb
 - lib/workers/event.rb
 - lib/workers/helpers.rb
 - lib/workers/log_proxy.rb
+- lib/workers/mailbox.rb
 - lib/workers/periodic_timer.rb
 - lib/workers/pool.rb
+- lib/workers/registry.rb
 - lib/workers/scheduler.rb
 - lib/workers/timer.rb
 - lib/workers/version.rb