tribe 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7425172d0fe26f65ff963c4f0b2742c3e21373fd
-  data.tar.gz: c117f5e53b430eb17cd75b804cbabb804028cbdc
+  metadata.gz: c286bf55aac4e1e85558bb56a3b49b2e84dcabc3
+  data.tar.gz: 1b0743b0e63db87ae6d0b0f81bacdd12c520ba46
 SHA512:
-  metadata.gz: 5e233c30e21178435eb07e4b4fcf687d9dabb4b1dfe3832f056c2e25b120d26b25f4f3e835b76be4e1cfad13ad1402626900cc0b96855a9bca2e698eb43a3847
-  data.tar.gz: da9e75d8da2798be63f340ca80d2231d08f94be59618b4a5d8edc9597a76e22e5d60d678016faa366fe08e4ec2c7476794877e34cea2d43aa0ecb381da78985c
+  metadata.gz: a87e8def58e14e31d464783f10c30c421ef0c8343b1a0abb8bc9075c73208ba32e28cc3d195dda7ffee0daa80072e16d2397392e5997810a51f57b35058a2673
+  data.tar.gz: bb336feb72e68638ad1d92b63826724ea07eb768f377eaa53a01639ba801a876adf5f80588067246922490482572913f5fd0e8478fe5ecca4406e476db00b364

data/README.md

@@ -29,29 +29,27 @@ Actors are light-weight objects that use asynchronous message passing for commun
 There are two types of methods that you create in your actors:
 
 1. *Command handlers* are prefixed with "on_" and define the types of commands your actor will process.
-2. *System handlers* are postfixed with "_handler" and are built into the actor system.  These are used for exception, shutdown, and cleanup handling.  It is important that you call the super method since their default behavior is used by the actor system.
+2. *System handlers* are postfixed with "_handler" and are built into the actor system.  These are used for exception, shutdown, and cleanup handling.
 
 To send a message you use the Actable#message! method and specify a command with an optional data parameter.
 The return value will always be nil since messaging is asynchronous.
 
+Note that the actors have a number of methods that end in ! (exclamation point or “bang”).
+All of these mthods are asynchronous and designed to be thread safe.
+More information on them will be provided throughout this readme.
+
     # Create your custom actor class.
     class MyActor < Tribe::Actor
       private
-      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
@@ -83,7 +81,6 @@ Actors that block for long periods of time should use a dedicated thread (:dedic
       :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 => 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).
     )
@@ -108,7 +105,6 @@ Both one-shot and periodic timers are provided.
       private
       def initialize(options = {})
         super
-
         timer(1, :timer, Time.now)
         periodic_timer(1, :periodic_timer, Time.now)
       end
@@ -151,7 +147,6 @@ No waiting for a result is involved and the actor will continue to process other
     class ActorA < Tribe::Actor
     private
       def exception_handler(e)
-        super
         puts concat_e("ActorA (#{identifier}) died.", e)
       end
 
@@ -176,7 +171,6 @@ No waiting for a result is involved and the actor will continue to process other
 
     class ActorB < Tribe::Actor
       def exception_handler(e)
-        super
         puts concat_e("ActorB (#{identifier}) died.", e)
       end
 
@@ -210,7 +204,6 @@ 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
 
@@ -231,7 +224,6 @@ The actor won't process any other events until the future has a result.
 
     class ActorB < Tribe::Actor
       def exception_handler(e)
-        super
         puts concat_e("ActorB (#{identifier}) died.", e)
       end
 
@@ -264,7 +256,7 @@ Below you will find a summary of performance recommendations regarding the use o
 ## Forwarding
 
 Messages and futures can be forwarded to other actors.
-This lets you build actors that delegate work to other actors.
+This lets you build routers that delegate work to other actors.
 
     # Create your router class.
     class MyRouter < Tribe::Actor
@@ -275,16 +267,14 @@ This lets you build actors that delegate work to other actors.
       end
 
       def on_process(event)
-        @processors[rand(100)].forward!(event)
+        forward!(@processors[rand(100)])
       end
 
       def exception_handler(e)
-        super
         puts concat_e("MyRouter (#{identifier}) died.", e)
       end
 
       def shutdown_handler(event)
-        super
         puts "MyRouter (#{identifier}) is shutting down.  Put cleanup code here."
         @processors.each { |p| p.shutdown! }
       end
@@ -293,21 +283,15 @@ This lets you build actors that delegate work to other actors.
     # Create your processor class.
     class MyProcessor < Tribe::Actor
       private
-      def initialize(options = {})
-        super
-      end
-
       def on_process(event)
         puts "MyProcessor (#{identifier}) received a process event (#{event.inspect})."
       end
 
       def exception_handler(e)
-        super
         puts concat_e("MyProcessor (#{identifier}) died.", e)
       end
 
       def shutdown_handler(event)
-        super
         puts "MyProcessor (#{identifier}) is shutting down.  Put cleanup code here."
       end
     end
@@ -323,6 +307,10 @@ This lets you build actors that delegate work to other actors.
     # Shutdown the router.
     router.shutdown!
 
+## Benchmarks
+
+  Please see the [performance] (https://github.com/chadrem/tribe/wiki/Performance "performance") wiki page for more information.
+
 ## TODO - missing features
 
 - Supervisors.

data/Rakefile

@@ -5,6 +5,7 @@ task :console do
   $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
 
   require 'tribe'
+  require 'tribe/benchmark'
   require 'irb'
 
   ARGV.clear

data/lib/tribe.rb

@@ -4,6 +4,7 @@ require 'workers'
 
 require 'tribe/safe_set'
 require 'tribe/exceptions'
+require 'tribe/event'
 require 'tribe/mailbox'
 require 'tribe/actor_state'
 require 'tribe/actable'

data/lib/tribe/actable.rb

@@ -18,12 +18,11 @@ module Tribe
       @logger = Workers::LogProxy.new(options[:logger])
       @_as = Tribe::ActorState.new
       @_as.dedicated = options[:dedicated] || false
-      @_as.mailbox = options[:mailbox] || Tribe::Mailbox.new
+      @_as.pool = @_as.dedicated ? Workers::Pool.new(:size => 1) : (options[:pool] || Workers.pool)
+      @_as.mailbox = Tribe::Mailbox.new(@_as.pool)
       @_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
 
       @_as.registry.register(self)
     end
@@ -37,37 +36,25 @@ module Tribe
 
     public
 
-    def message!(command, data = nil)
-      return forward!(Workers::Event.new(command, data))
+    def event!(event)
+      push_event(event)
+
+      return nil
     end
 
-    def forward!(event)
-      return nil unless alive?
+    def message!(command, data = nil, source = nil)
+      event = Tribe::Event.new(command, data, source)
 
-      @_as.mailbox.push(event) do
-        @_as.pool.perform { process_events }
-      end
+      push_event(event)
 
       return nil
     end
 
-    def future!(command, data = nil)
-      @_as.futures ||= Tribe::SafeSet.new # Lazy instantiation for performance.
+    def future!(command, data = nil, source = nil)
+      event = Tribe::Event.new(command, data, source)
+      event.future = future = Tribe::Future.new
 
-      future = Tribe::Future.new
-      @_as.futures.add(future)
-
-      perform! do
-        begin
-          result = event_handler(Workers::Event.new(command, data))
-          future.result = result
-        rescue Exception => exception
-          future.result = exception
-          raise
-        ensure
-          @_as.futures.delete(future)
-        end
-      end
+      push_event(event)
 
       return future
     end
@@ -81,7 +68,7 @@ module Tribe
     end
 
     def alive?
-      @_as.mailbox.synchronize { return @_as.alive }
+      @_as.mailbox.alive?
     end
 
     def name
@@ -99,9 +86,23 @@ module Tribe
 
     private
 
-    # The return value is used as the result of a future.
     def event_handler(event)
-      return send("on_#{event.command}", event)
+      result = nil
+      @_as.active_event = event
+
+      begin
+        result = send("on_#{event.command}", event)
+      rescue Exception => e
+        result = e
+        raise
+      ensure
+        if event.future && @_as.active_event
+          event.future.result = result
+        end
+        @_as.active_event = nil
+      end
+
+      return nil
     end
 
     def exception_handler(exception)
@@ -120,10 +121,9 @@ module Tribe
 
     def cleanup_handler(exception = nil)
       @_as.pool.shutdown if @_as.dedicated
-      @_as.mailbox.synchronize { @_as.alive = false }
+      @_as.mailbox.kill
       @_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
@@ -181,8 +181,21 @@ module Tribe
     # Notes: These are used by the actor system and you should never call them directly.
     #
 
+    def forward!(dest)
+      dest.event!(@_as.active_event)
+      @_as.active_event = nil
+
+      return nil
+    end
+
+    def push_event(event)
+      @_as.mailbox.push(event) do
+        process_events
+      end
+    end
+
     def process_events
-      while (event = @_as.mailbox.shift)
+      while (event = @_as.mailbox.obtain_and_shift)
         case event.command
         when :shutdown
           cleanup_handler
@@ -199,7 +212,7 @@ module Tribe
       exception_handler(exception)
     ensure
       @_as.mailbox.release do
-        @_as.pool.perform { process_events if @_as.alive }
+        process_events
       end
 
       return nil

data/lib/tribe/actor_state.rb

@@ -7,7 +7,6 @@ module Tribe
     attr_accessor :timers
     attr_accessor :name
     attr_accessor :pool
-    attr_accessor :alive
-    attr_accessor :futures
+    attr_accessor :active_event
   end
 end

data/lib/tribe/benchmark.rb

@@ -0,0 +1 @@
+require 'tribe/benchmark/throughput'

data/lib/tribe/benchmark/throughput.rb

@@ -0,0 +1,74 @@
+module Tribe
+  module Benchmark
+    module Throughput
+      MAX_INCR    = 100000
+      ACTOR_COUNT = 100000
+      COUNTERS    = 20
+
+      def self.run
+        ACTOR_COUNT.times do |i|
+          actor = Tribe.registry["actor_#{i}"]
+          actor.shutdown! if actor
+        end
+
+        $start_time = Time.now.utc
+        $finished = 0
+        $lock = Mutex.new
+
+        ACTOR_COUNT.times do |i|
+          MyActor.new(:name => "actor_#{i}")
+        end
+
+        COUNTERS.times do |i|
+          Tribe.registry["actor_#{rand(ACTOR_COUNT)}"].message!(:do_stuff, MyData.new("data_#{i}"))
+        end
+
+        $lock.synchronize do
+          puts 'Please wait...'
+        end
+      end
+
+      def self.stop
+      end
+
+      class MyData
+        def initialize(name)
+          @name = name
+          @counter = 0
+          @start_time = Time.now
+        end
+
+        def increment
+          @counter += 1
+
+          if @counter >= MAX_INCR
+            $lock.synchronize do
+              $finished += 1
+
+              if $finished == COUNTERS
+                puts "\nFinished! Rate=#{(COUNTERS * MAX_INCR).to_f / (Time.now.utc - $start_time).to_f } msgs/sec\n"
+              end
+            end
+
+            return false
+          end
+
+          return true
+        end
+      end
+
+      class MyActor < Tribe::Actor
+        private
+        def on_do_stuff(event)
+          if event.data.increment
+            Tribe.registry["actor_#{rand(ACTOR_COUNT)}"].message!(:do_stuff, event.data)
+          end
+        end
+
+        def exception_handler(e)
+          puts concat_e("MyActor (#{identifier}) died.", e)
+        end
+      end
+    end
+  end
+end

data/lib/tribe/event.rb

@@ -0,0 +1,15 @@
+module Tribe
+  class Event
+
+    attr_accessor :command
+    attr_accessor :data
+    attr_accessor :source
+    attr_accessor :future
+
+    def initialize(command, data, source = nil)
+      @command = command
+      @data = data
+      @source = source
+    end
+  end
+end

data/lib/tribe/mailbox.rb

@@ -1,44 +1,64 @@
 module Tribe
   class Mailbox
-    def initialize(options = {})
+    def initialize(pool)
+      @pool = pool
       @messages = []
+      @alive = true
       @mutex = Mutex.new
     end
 
     def push(event, &block)
       @mutex.synchronize do
+        return nil unless @alive
+
         @messages.push(event)
-        block.call unless @current_thread
+        @pool.perform { block.call } unless @owner_thread
       end
 
       return nil
     end
 
-    def shift
+    def obtain_and_shift
       @mutex.synchronize do
-        return nil if @current_thread && @current_thread != Thread.current
-
-        @current_thread = Thread.current unless @current_thread
+        return nil unless @alive
 
-        return @messages.shift
+        if @owner_thread
+          if @owner_thread == Thread.current
+            return @messages.shift
+          else
+            return nil
+          end
+        else
+          @owner_thread = Thread.current
+          return @messages.shift
+        end
       end
     end
 
     def release(&block)
       @mutex.synchronize do
-        @current_thread = nil
-        block.call if block && @messages.length > 0
+        return nil unless @owner_thread == Thread.current
+
+        @owner_thread = nil
+        @pool.perform { block.call } if @alive && @messages.length > 0
       end
 
       return nil
     end
 
-    def synchronize(&block)
+    def kill
       @mutex.synchronize do
-        block.call
+        @alive = false
+        @messages.clear
       end
 
       return nil
     end
+
+    def alive?
+      @mutex.synchronize do
+        return @alive
+      end
+    end
   end
 end

data/lib/tribe/version.rb

@@ -1,3 +1,3 @@
 module Tribe
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tribe
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Chad Remesch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-08 00:00:00.000000000 Z
+date: 2013-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: workers
@@ -41,7 +41,10 @@ files:
 - lib/tribe/actable.rb
 - lib/tribe/actor.rb
 - lib/tribe/actor_state.rb
+- lib/tribe/benchmark.rb
+- lib/tribe/benchmark/throughput.rb
 - lib/tribe/dedicated_actor.rb
+- lib/tribe/event.rb
 - lib/tribe/exceptions.rb
 - lib/tribe/future.rb
 - lib/tribe/mailbox.rb