tribe 0.1.0 → 0.2.0

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    tribe (0.0.11)
-      workers (= 0.1.1)
+    tribe (0.1.0)
+      workers (= 0.1.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    workers (0.1.1)
+    workers (0.1.2)
 
 PLATFORMS
   java

data/README.md

@@ -30,49 +30,44 @@ Or install it yourself as:
       def initialize(options = {})
         super
       end
-      
+
       def on_my_custom(event)
         puts "Received a custom event (#{event.inspect})"
       end
-      
+
       def exception_handler(e)
         super
         puts concat_e("MyActor (#{identifier}) died.", e)
       end
-      
+
       def shutdown_handler(event)
         super
         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 global registry.
     100.times do |i|
       actor = Tribe.registry["my_actor_#{i}"]
       actor.enqueue(:my_custom, 'hello world')
     end
-    
+
     # Shutdown the actors.
     100.times do |i|
       actor = Tribe.registry["my_actor_#{i}"]
       actor.enqueue(:shutdown)
     end
 
-### Implementation notes
-Because actors use a shared thread pool, it is important that they don't block for long periods of time (short periods are fine).
+#### Implementation notes
+*Important*: Because actors use a shared thread pool, it is important that they don't block for long periods of time (short periods are fine).
 Actors that block for long periods of time should use a dedicated thread (:dedicated => true or subclass from Tribe::DedicatedActor).
 
-## Registries
-
-Registries hold references to named actors.
-In general you shouldn't have to create your own since there is a global one (Tribe.registry).
-
-## Options (defaults below):
+#### Options (defaults below):
 
     actor = Tribe::Actor.new(
       :logger => nil,                   # Ruby logger instance.
@@ -90,6 +85,17 @@ In general you shouldn't have to create your own since there is a global one (Tr
       :name => nil                      # The name of the actor (must be unique in the registry).
     )
 
+## Registries
+
+Registries hold references to named actors so that you can easily find them.
+In general you shouldn't have to create your own since there is a global one (Tribe.registry).
+
+    actor = Tribe::Actor.new(:name => 'some_actor')
+
+    if actor == Tribe.registry['some_actor']
+      puts 'Successfully found some_actor in the registry.'
+    end
+
 ## Timers
 
 Actors can create timers to perform some work in the future.
@@ -127,10 +133,137 @@ Both one-shot and periodic timers are provides.
       actor.enqueue(:shutdown)
     end
 
+## Futures (experimental)
+
+Futures allow an actor to ask another actor to perform a computation and then return the result.
+Tribe includes both blocking and non-blocking actors.
+You should prefer to use non-blocking actors in your code when possible due to performance reasons (see details below).
+
+#### Non-blocking
+
+Non-blocking actors are asynchronous and use callbacks.
+No waiting for a result is involved.
+The actor will continue to process other events.
+
+    class ActorA < Tribe::Actor
+    private
+      def exception_handler(e)
+        super
+        puts concat_e("ActorA (#{identifier}) died.", e)
+      end
+
+      def on_start(event)
+        friend = registry['actor_b']
+
+        future = friend.enqueue_future(:compute, 10)
+
+        future.success do |result|
+          perform do
+            puts "ActorA (#{identifier}) future result: #{result}"
+          end
+        end
+
+        future.failure do |exception|
+          perform do
+            puts "ActorA (#{identifier}) future failure: #{exception}"
+          end
+        end
+      end
+    end
+
+    class ActorB < Tribe::Actor
+      def exception_handler(e)
+        super
+        puts concat_e("ActorB (#{identifier}) died.", e)
+      end
+
+      def on_compute(event)
+        return factorial(event.data)
+      end
+
+      def factorial(num)
+        return 1 if num <= 0
+        return num * factorial(num - 1)
+      end
+    end
+
+    actor_a = ActorA.new(:name => 'actor_a')
+    actor_b = ActorB.new(:name => 'actor_b')
+
+    actor_a.enqueue(:start)
+
+    actor_a.enqueue(:shutdown)
+    actor_b.enqueue(:shutdown)
+
+*Important*: You must use Actor#perform inside the above callbacks.
+This ensures that your code executes within the context of the correct actor.
+Failure to do so will result in race conditions and other nasty things.
+
+#### Blocking
+
+Blocking actors are synchronous.
+The actor won't process any other events until the future has a result.
+
+    class ActorA < Tribe::Actor
+    private
+      def exception_handler(e)
+        super
+        puts concat_e("ActorA (#{identifier}) died.", e)
+      end
+
+      def on_start(event)
+        friend = registry['actor_b']
+
+        future = friend.enqueue_future(:compute, 10)
+
+        future.wait # The current thread will sleep until a result is available.
+
+        if future.success?
+          puts "ActorA (#{identifier}) future result: #{future.result}"
+        else
+          puts "ActorA (#{identifier}) future failure: #{future.result}"
+        end
+      end
+    end
+
+    class ActorB < Tribe::Actor
+      def exception_handler(e)
+        super
+        puts concat_e("ActorB (#{identifier}) died.", e)
+      end
+
+      def on_compute(event)
+        return factorial(event.data)
+      end
+
+      def factorial(num)
+        return 1 if num <= 0
+        return num * factorial(num - 1)
+      end
+    end
+
+    actor_a = ActorA.new(:name => 'actor_a')
+    actor_b = ActorB.new(:name => 'actor_b')
+
+    actor_a.enqueue(:start)
+
+    actor_a.enqueue(:shutdown)
+    actor_b.enqueue(:shutdown)
+
+#### 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.
+
+Tribe is designed specifically to support having 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.
+Each dedicated actor runs in a separate thread (instead of a shared thread pool).
+The downside to using dedicated actors is that they consume more resources and you can't have as many of them.
+
 ## TODO - missing features
 
-- Futures.
-- Workers::Timer integration.
 - Supervisors.
 - Linking.
 

data/lib/tribe/actable.rb

@@ -1,80 +1,132 @@
+# 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
 
-    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
+    private
 
-      @registry.register(self)
+    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
+
+      @_registry.register(self)
     end
 
+    public
+
     def enqueue(command, data = nil)
       return false unless alive?
 
-      @mailbox.push(Workers::Event.new(command, data)) do
-        @pool.perform { process_events }
+      @_mailbox.push(Workers::Event.new(command, data)) do
+        @_pool.perform { process_events }
       end
 
       return true
     end
 
+    def enqueue_future(command, data = nil)
+      future = Tribe::Future.new
+      @_futures.add(future)
+
+      perform do
+        begin
+          result = result = process_event(Workers::Event.new(command, data))
+          future.result = result
+        rescue Exception => e
+          future.result = e
+          raise
+        ensure
+          @_futures.delete(future)
+        end
+      end
+
+      return future
+    end
+
     def alive?
-      @mailbox.synchronize { return @alive }
+      @_mailbox.synchronize { return @_alive }
     end
 
     def name
-      return @name
+      return @_name
     end
 
     def identifier
-      return @name ? "#{object_id}:#{@name}" : object_id
+      return @_name ? "#{object_id}:#{@_name}" : object_id
+    end
+
+    def shutdown
+      return enqueue(:shutdown)
+    end
+
+    def perform(&block)
+      return enqueue(:perform, block)
     end
 
     private
 
+    def registry
+      return @_registry
+    end
+
+    def pool
+      return @_pool
+    end
+
+    def logger
+      return @_logger
+    end
+
     def process_events
-      while (event = @mailbox.shift)
+      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
+      cleanup(e)
       exception_handler(e)
     ensure
-      @mailbox.release do
-        @pool.perform { process_events if @alive }
+      @_mailbox.release do
+        @_pool.perform { process_events if @_alive }
       end
 
       return nil
     end
 
-    def cleanup
-      @pool.shutdown if @dedicated
-      @mailbox.synchronize { @alive = false }
-      @registry.unregister(self)
+    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 }
 
       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)
-      send("on_#{event.command}", event)
-
-      return nil
+      return send("on_#{event.command}", event)
     end
 
     # Override and call super as necessary.
@@ -84,40 +136,36 @@ module Tribe
 
     # Override and call super as necessary.
     def shutdown_handler(event)
-      shutdown_timers
-
       return nil
     end
 
-    def shutdown_timers
-      @timers.each do |timer|
-        timer.cancel
-      end
+    def perform_handler(event)
+      event.data.call
 
       return nil
     end
 
     def timer(delay, command, data = nil)
-      timer = Workers::Timer.new(delay, :scheduler => @scheduler) do
-        @timers.delete(timer)
+      timer = Workers::Timer.new(delay, :scheduler => @_scheduler) do
+        @_timers.delete(timer)
         enqueue(command, data)
       end
 
-      @timers.add(timer)
+      @_timers.add(timer)
 
       return timer
     end
 
     def periodic_timer(delay, command, data = nil)
-      timer = Workers::PeriodicTimer.new(delay, :scheduler => @scheduler) do
+      timer = Workers::PeriodicTimer.new(delay, :scheduler => @_scheduler) do
         enqueue(command, data)
         unless alive?
-          @timers.delete(timer)
+          @_timers.delete(timer)
           timer.cancel
         end
       end
 
-      @timers.add(timer)
+      @_timers.add(timer)
 
       return timer
     end

data/lib/tribe/exceptions.rb

@@ -0,0 +1,3 @@
+module Tribe
+  class ActorShutdownError < RuntimeError; end
+end

data/lib/tribe/future.rb

@@ -0,0 +1,98 @@
+module Tribe
+  class Future
+    def initialize
+      @state = :initialized
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @result = nil
+      @success_callback = nil
+      @failure_callback = nil
+
+      return nil
+    end
+
+    def finished?
+      @mutex.synchronize do
+        return @state == :finished
+      end
+    end
+
+    def result=(val)
+      @mutex.synchronize do
+        raise 'Result must only be set once.' unless @state == :initialized
+
+        @result = val
+        @state = :finished
+        @condition.signal
+
+        if val.is_a?(Exception)
+          @failure_callback.call(val) if @failure_callback
+        else
+          @success_callback.call(val) if @success_callback
+        end
+
+        return nil
+      end
+    end
+
+    def result
+      @mutex.synchronize do
+        raise 'Result must be set first.' unless @state == :finished
+
+        return @result
+      end
+    end
+
+    def wait
+      @mutex.synchronize do
+        return if @state == :finished
+
+        @condition.wait(@mutex)
+
+        return nil
+      end
+    end
+
+    def success?
+      @mutex.synchronize do
+        raise 'Result must be set first.' unless @state == :finished
+
+        return !@result.is_a?(Exception)
+      end
+    end
+
+    def failure?
+      return !success?
+    end
+
+    def success(&block)
+      @mutex.synchronize do
+        case @state
+        when :initialized
+          @success_callback = block
+        when :finished
+          yield(@result) unless @result.is_a?(Exception)
+        else
+          raise 'Invalid state.'
+        end
+
+        return nil
+      end
+    end
+
+    def failure(&block)
+      @mutex.synchronize do
+        case @state
+        when :initialized
+          @failure_callback = block
+        when :finished
+          yield(@result) if @result.is_a?(Exception)
+        else
+          raise 'Invalid state.'
+        end
+
+        return nil
+      end
+    end
+  end
+end

data/lib/tribe/version.rb

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

data/lib/tribe.rb

@@ -3,11 +3,13 @@ require 'set'
 require 'workers'
 
 require 'tribe/safe_set'
+require 'tribe/exceptions'
 require 'tribe/mailbox'
 require 'tribe/actable'
 require 'tribe/actor'
 require 'tribe/dedicated_actor'
 require 'tribe/registry'
+require 'tribe/future'
 
 module Tribe
   def self.registry

data/tribe.gemspec

@@ -15,5 +15,5 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Tribe::VERSION
 
-  gem.add_dependency('workers', '0.1.1')
+  gem.add_dependency('workers', '0.1.2')
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tribe
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-24 00:00:00.000000000 Z
+date: 2013-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: workers
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.1.2
 description: Tribe is a Ruby gem that implements event-driven actors.
 email:
 - chad@remesch.com
@@ -44,6 +44,8 @@ files:
 - lib/tribe/actable.rb
 - lib/tribe/actor.rb
 - lib/tribe/dedicated_actor.rb
+- lib/tribe/exceptions.rb
+- lib/tribe/future.rb
 - lib/tribe/mailbox.rb
 - lib/tribe/registry.rb
 - lib/tribe/safe_set.rb