tribe 0.2.0 → 0.2.1

data/README.md

@@ -2,9 +2,10 @@
 
 Tribe is a Ruby gem that implements event-driven [actors] (http://en.wikipedia.org/wiki/Actor_model "actors").
 Actors are lightweight concurrent objects that use asynchronous message passing for communication.
-Tribe focuses on high performance, low latency, an easy to use API, and flexibility.
-It is built on top of the [Workers] (https://github.com/chadrem/workers "Workers") gem, which allows it to support many actors (millions should be possible).
-Actors can use a shared thread pool (default) or dedicted threads.
+
+Tribe focuses on high performance, low latency, a simple API, and flexibility.
+It's goal is to support at least one million actors running on a small group of threads.
+It is built on top of the [Workers] (https://github.com/chadrem/workers "Workers") gem.
 
 Event-driven servers can be built using [Tribe EM] (https://github.com/chadrem/tribe_em "Tribe EM").
 
@@ -78,12 +79,8 @@ Actors that block for long periods of time should use a dedicated thread (:dedic
       :name => nil                      # The name of the actor (must be unique in the registry).
     )
 
-    actor = Tribe::DedicatedActor.new(
-      :logger => nil,                   # Ruby logger instance.
-      :mailbox => Tribe::Mailbox.new,   # The mailbox used to receive events.
-      :registry => Tribe.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).
-    )
+    The DedicatedActor class is a simple wrapper around the Actor class.
+    It takes all the same options except for :pool and :dedicated since they aren't applicable.
 
 ## Registries
 
@@ -99,7 +96,7 @@ In general you shouldn't have to create your own since there is a global one (Tr
 ## Timers
 
 Actors can create timers to perform some work in the future.
-Both one-shot and periodic timers are provides.
+Both one-shot and periodic timers are provided.
 
     class MyActor < Tribe::Actor
       private
@@ -253,9 +250,9 @@ The actor won't process any other events until the future has a result.
 #### Futures and Performance
 
 You should prefer non-blocking futures as much as possible in your application code.
-This is because blocking futures (Future#wait) causes the current actor (and thread) to sleep.
+This is because a blocking future (Future#wait) causes the current actor (and thread) to sleep.
 
-Tribe is designed specifically to support having a large number of actors running on a small number of threads.
+Tribe is designed specifically to support a large number of actors running on a small number of threads.
 Thus, you will run into performance and/or deadlock problems if too many actors are waiting at the same time.
 
 If you choose to use blocing futures then it is highly recommended that you only use them with dedicated actors.

data/lib/tribe.rb

@@ -5,6 +5,7 @@ require 'workers'
 require 'tribe/safe_set'
 require 'tribe/exceptions'
 require 'tribe/mailbox'
+require 'tribe/actor_state'
 require 'tribe/actable'
 require 'tribe/actor'
 require 'tribe/dedicated_actor'

data/lib/tribe/actable.rb

@@ -1,54 +1,66 @@
-# This module is designed to be mixed in with your application code.
-# Because of this, all instance variables are prefixed with an underscore.
-# The hope is to minimize the chances of conflicts.
-# Long term my goal is to move all of these variables into an ActorState object.
-
 module Tribe
   module Actable
     include Workers::Helpers
 
+    #
+    # Initialization method.
+    # Notes: Call this in your constructor.
+    #
+
     private
 
     def init_actable(options = {})
-      @_logger = Workers::LogProxy.new(options[:logger])
-      @_dedicated = options[:dedicated] || false
-      @_mailbox = options[:mailbox] || Tribe::Mailbox.new
-      @_registry = options[:registry] || Tribe.registry
-      @_scheduler = options[:scheduler] || Workers.scheduler
-      @_timers = Tribe::SafeSet.new
-      @_name = options[:name]
-      @_pool = @_dedicated ? Workers::Pool.new(:size => 1) : (options[:pool] || Workers.pool)
-      @_alive = true
-      @_futures = Tribe::SafeSet.new
+      # Symbols aren't GCed in JRuby so force string names.
+      if options[:name] && !options[:name].is_a?(String)
+        raise Tribe::ActorNameError.new('Name must be a string.')
+      end
+
+      @logger = Workers::LogProxy.new(options[:logger])
+      @_as = Tribe::ActorState.new
+      @_as.dedicated = options[:dedicated] || false
+      @_as.mailbox = options[:mailbox] || Tribe::Mailbox.new
+      @_as.registry = options[:registry] || Tribe.registry
+      @_as.scheduler = options[:scheduler]
+      @_as.name = options[:name]
+      @_as.pool = @_as.dedicated ? Workers::Pool.new(:size => 1) : (options[:pool] || Workers.pool)
+      @_as.alive = true
 
-      @_registry.register(self)
+      @_as.registry.register(self)
     end
 
+    #
+    # Thread safe public methods.
+    # Notes: These are the methods that actors use to communicate with each other.
+    #        Actors should avoid sharing mutable state in order to remain thread safe.
+    #
+
     public
 
     def enqueue(command, data = nil)
       return false unless alive?
 
-      @_mailbox.push(Workers::Event.new(command, data)) do
-        @_pool.perform { process_events }
+      @_as.mailbox.push(Workers::Event.new(command, data)) do
+        @_as.pool.perform { process_events }
       end
 
       return true
     end
 
     def enqueue_future(command, data = nil)
+      @_as.futures ||= Tribe::SafeSet.new # Lazy instantiation for performance.
+
       future = Tribe::Future.new
-      @_futures.add(future)
+      @_as.futures.add(future)
 
       perform do
         begin
-          result = result = process_event(Workers::Event.new(command, data))
+          result = event_handler(Workers::Event.new(command, data))
           future.result = result
-        rescue Exception => e
-          future.result = e
+        rescue Exception => exception
+          future.result = exception
           raise
         ensure
-          @_futures.delete(future)
+          @_as.futures.delete(future)
         end
       end
 
@@ -56,15 +68,15 @@ module Tribe
     end
 
     def alive?
-      @_mailbox.synchronize { return @_alive }
+      @_as.mailbox.synchronize { return @_as.alive }
     end
 
     def name
-      return @_name
+      return @_as.name
     end
 
     def identifier
-      return @_name ? "#{object_id}:#{@_name}" : object_id
+      return @_as.name ? "#{object_id}:#{@_as.name}" : object_id
     end
 
     def shutdown
@@ -75,99 +87,117 @@ module Tribe
       return enqueue(:perform, block)
     end
 
+    #
+    # Private event handlers.
+    # Notes: These methods are designed to be overriden (make sure you call super).
+    #
+
     private
 
-    def registry
-      return @_registry
+    # The return value is used as the result of a future.
+    def event_handler(event)
+      return send("on_#{event.command}", event)
     end
 
-    def pool
-      return @_pool
+    def exception_handler(exception)
+      return nil
     end
 
-    def logger
-      return @_logger
+    def shutdown_handler(event)
+      return nil
     end
 
-    def process_events
-      while (event = @_mailbox.shift)
-        case event.command
-        when :shutdown
-          cleanup
-          shutdown_handler(event)
-        when :perform
-          perform_handler(event)
-        else
-          process_event(event)
-        end
-      end
-
-    rescue Exception => e
-      cleanup(e)
-      exception_handler(e)
-    ensure
-      @_mailbox.release do
-        @_pool.perform { process_events if @_alive }
-      end
+    def perform_handler(event)
+      event.data.call
 
       return nil
     end
 
-    def cleanup(e = nil)
-      @_pool.shutdown if @_dedicated
-      @_mailbox.synchronize { @_alive = false }
-      @_registry.unregister(self)
-      @_timers.each { |t| t.cancel }
-      @_futures.each { |f| f.result = e || Tribe::ActorShutdownError.new }
+    def cleanup_handler(exception = nil)
+      @_as.pool.shutdown if @_as.dedicated
+      @_as.mailbox.synchronize { @_as.alive = false }
+      @_as.registry.unregister(self)
+      @_as.timers.each { |t| t.cancel } if @_as.timers
+      @_as.futures.each { |f| f.result = exception || Tribe::ActorShutdownError.new } if @_as.futures
 
       return nil
     end
 
-    # Override and call super as necessary.
-    # Note that the return value is used as the result of a future.
-    def process_event(event)
-      return send("on_#{event.command}", event)
-    end
+    #
+    # Private API methods.
+    # Notes: Use these methods internally in your actor.
+    #
 
-    # Override and call super as necessary.
-    def exception_handler(e)
-      return nil
-    end
+    private
 
-    # Override and call super as necessary.
-    def shutdown_handler(event)
-      return nil
+    def registry
+      return @_as.registry
     end
 
-    def perform_handler(event)
-      event.data.call
-
-      return nil
+    def pool
+      return @_as.pool
     end
 
     def timer(delay, command, data = nil)
-      timer = Workers::Timer.new(delay, :scheduler => @_scheduler) do
-        @_timers.delete(timer)
+      # Lazy instantiation for performance.
+      @_as.scheduler ||= Workers.scheduler
+      @_as.timers ||= Tribe::SafeSet.new
+
+      timer = Workers::Timer.new(delay, :scheduler => @_as.scheduler) do
+        @_as.timers.delete(timer)
         enqueue(command, data)
       end
 
-      @_timers.add(timer)
+      @_as.timers.add(timer)
 
       return timer
     end
 
     def periodic_timer(delay, command, data = nil)
-      timer = Workers::PeriodicTimer.new(delay, :scheduler => @_scheduler) do
+      # Lazy instantiation for performance.
+      @_as.scheduler ||= Workers.scheduler
+      @_as.timers ||= Tribe::SafeSet.new
+
+      timer = Workers::PeriodicTimer.new(delay, :scheduler => @_as.scheduler) do
         enqueue(command, data)
         unless alive?
-          @_timers.delete(timer)
+          @_as.timers.delete(timer)
           timer.cancel
         end
       end
 
-      @_timers.add(timer)
+      @_as.timers.add(timer)
 
       return timer
     end
+
+    #
+    # Private internal methods.
+    # Notes: These are used by the actor system and you should never call them directly.
+    #
+
+    def process_events
+      while (event = @_as.mailbox.shift)
+        case event.command
+        when :shutdown
+          cleanup_handler
+          shutdown_handler(event)
+        when :perform
+          perform_handler(event)
+        else
+          event_handler(event)
+        end
+      end
+
+    rescue Exception => exception
+      cleanup_handler(exception)
+      exception_handler(exception)
+    ensure
+      @_as.mailbox.release do
+        @_as.pool.perform { process_events if @_as.alive }
+      end
+
+      return nil
+    end
   end
 end

data/lib/tribe/actor_state.rb

@@ -0,0 +1,13 @@
+module Tribe
+  class ActorState
+    attr_accessor :dedicated
+    attr_accessor :mailbox
+    attr_accessor :registry
+    attr_accessor :scheduler
+    attr_accessor :timers
+    attr_accessor :name
+    attr_accessor :pool
+    attr_accessor :alive
+    attr_accessor :futures
+  end
+end

data/lib/tribe/exceptions.rb

@@ -1,3 +1,8 @@
 module Tribe
   class ActorShutdownError < RuntimeError; end
+  class ActorNameError < RuntimeError; end
+
+  class FutureError < RuntimeError; end
+
+  class RegistryError < RuntimeError; end
 end

data/lib/tribe/future.rb

@@ -19,7 +19,7 @@ module Tribe
 
     def result=(val)
       @mutex.synchronize do
-        raise 'Result must only be set once.' unless @state == :initialized
+        raise Tribe::FutureError.new('Result must only be set once.') unless @state == :initialized
 
         @result = val
         @state = :finished
@@ -37,7 +37,7 @@ module Tribe
 
     def result
       @mutex.synchronize do
-        raise 'Result must be set first.' unless @state == :finished
+        raise Tribe::FutureError.new('Result must be set first.') unless @state == :finished
 
         return @result
       end
@@ -55,7 +55,7 @@ module Tribe
 
     def success?
       @mutex.synchronize do
-        raise 'Result must be set first.' unless @state == :finished
+        raise Tribe::FutureError.new('Result must be set first.') unless @state == :finished
 
         return !@result.is_a?(Exception)
       end
@@ -73,7 +73,7 @@ module Tribe
         when :finished
           yield(@result) unless @result.is_a?(Exception)
         else
-          raise 'Invalid state.'
+          raise Tribe::FutureError.new('Invalid state.')
         end
 
         return nil
@@ -88,7 +88,7 @@ module Tribe
         when :finished
           yield(@result) if @result.is_a?(Exception)
         else
-          raise 'Invalid state.'
+          raise Tribe::FutureError.new('Invalid state.')
         end
 
         return nil

data/lib/tribe/registry.rb

@@ -8,7 +8,7 @@ module Tribe
 
     def register(actor)
       @mutex.synchronize do
-        raise("Actor already exists (#{actor.name}).") if @actors_by_name.key?(actor.name)
+        raise Tribe::RegistryError.new("Actor already exists (#{actor.name}).") if @actors_by_name.key?(actor.name)
 
         @actors_by_name[actor.name] = actor if actor.name
         @actors_by_oid[actor.object_id] = actor

data/lib/tribe/version.rb

@@ -1,3 +1,3 @@
 module Tribe
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tribe
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-25 00:00:00.000000000 Z
+date: 2013-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: workers
@@ -43,6 +43,7 @@ files:
 - lib/tribe.rb
 - lib/tribe/actable.rb
 - lib/tribe/actor.rb
+- lib/tribe/actor_state.rb
 - lib/tribe/dedicated_actor.rb
 - lib/tribe/exceptions.rb
 - lib/tribe/future.rb