tribe 0.2.3 → 0.3.0

checksums.yaml

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

data/README.md

@@ -25,13 +25,13 @@ Or install it yourself as:
 
 ## Actors
 
-Actors are light-weight objects which use asynchronous message passing for communcation.
+Actors are light-weight objects that use asynchronous message passing for communcation.
 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.
 
-To send a message you use the "enqueue" method and specify a command with an optional data parameter.
+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.
 
     # Create your custom actor class.
@@ -42,7 +42,7 @@ The return value will always be nil since messaging is asynchronous.
       end
 
       def on_my_custom(event)
-        puts "Received a custom event (#{event.inspect})"
+        puts "Received a custom event (#{event.inspect})."
       end
 
       def exception_handler(e)
@@ -64,13 +64,13 @@ The return value will always be nil since messaging is asynchronous.
     # Send an event to each actor.
     100.times do |i|
       actor = Tribe.registry["my_actor_#{i}"]
-      actor.enqueue(:my_custom, 'hello world')
+      actor.message!(:my_custom, 'hello world')
     end
 
     # Shutdown the actors.
     100.times do |i|
       actor = Tribe.registry["my_actor_#{i}"]
-      actor.enqueue(:shutdown)
+      actor.shutdown!
     end
 
 #### Implementation
@@ -133,27 +133,20 @@ Both one-shot and periodic timers are provided.
     # Shutdown the actors.
     10.times do |i|
       actor = Tribe.registry["my_actor_#{i}"]
-      actor.enqueue(:shutdown)
+      actor.shutdown!
     end
 
 ## Futures
 
-As mentioned above, message passing with the "enqueue" method is asynchronous and always returns nil.
+As mentioned above, message passing with the Actable#message! method is asynchronous and always returns nil.
 This can be a pain since in many cases you will be interested in the result.
-
-The "enqueue_future" method helps solve this problem by returning a a Tribe::Future object instead of nil.
-You can then use this object to obtain the result when it becomes available sometime in the future.
-
-Tribe includes both blocking and non-blocking futures.
-You should prefer to use non-blocking futures for performance reasons (see details below).
-
-In situations where an actor dies, your future will receive the raised exception as the result.
+The Actable#future! method solves this problem by returning a Tribe::Future object instead of nil.
+You can then use this object to obtain the result when it becomes available.
 
 #### Non-blocking
 
 Non-blocking futures are asynchronous and use callbacks.
-No waiting for a result is involved.
-The actor will continue to process other events.
+No waiting for a result is involved and the actor will continue to process other events.
 
     class ActorA < Tribe::Actor
     private
@@ -165,16 +158,16 @@ The actor will continue to process other events.
       def on_start(event)
         friend = registry['actor_b']
 
-        future = friend.enqueue_future(:compute, 10)
+        future = friend.future!(:compute, 10)
 
         future.success do |result|
-          perform do
+          perform! do
             puts "ActorA (#{identifier}) future result: #{result}"
           end
         end
 
         future.failure do |exception|
-          perform do
+          perform! do
             puts "ActorA (#{identifier}) future failure: #{exception}"
           end
         end
@@ -200,14 +193,14 @@ The actor will continue to process other events.
     actor_a = ActorA.new(:name => 'actor_a')
     actor_b = ActorB.new(:name => 'actor_b')
 
-    actor_a.enqueue(:start)
+    actor_a.message!(:start)
 
-    actor_a.enqueue(:shutdown)
-    actor_b.enqueue(:shutdown)
+    actor_a.shutdown!
+    actor_b.shutdown!
 
-*Important*: You must use Actor#perform inside the above callbacks.
+*Important*: You must use Actable#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 many nasty things.
+Failure to do so will result in unexpected behavior (thread safety will be lost)!
 
 #### Blocking
 
@@ -224,7 +217,7 @@ The actor won't process any other events until the future has a result.
       def on_start(event)
         friend = registry['actor_b']
 
-        future = friend.enqueue_future(:compute, 10)
+        future = friend.future!(:compute, 10)
 
         future.wait # The current thread will sleep until a result is available.
 
@@ -255,32 +248,87 @@ The actor won't process any other events until the future has a result.
     actor_a = ActorA.new(:name => 'actor_a')
     actor_b = ActorB.new(:name => 'actor_b')
 
-    actor_a.enqueue(:start)
+    actor_a.message!(:start)
+
+    actor_a.shutdown!
+    actor_b.shutdown!
+
+#### Performance Summary
+
+Below you will find a summary of performance recommendations regarding the use of futures:
+
+- Use Actable#message! unless you really need Actable#future! since futures have overhead.
+- If you use Actable#future!, prefer the non-blocking API over the blocking one.
+- If you use the blocking API, the actor calling Future#wait should use a dedicated worker thread.
+
+## Forwarding
+
+Messages and futures can be forwarded to other actors.
+This lets you build actors that delegate work to other actors.
+
+    # Create your router class.
+    class MyRouter < Tribe::Actor
+      private
+      def initialize(options = {})
+        super
+        @processors = 100.times.map { MyProcessor.new }
+      end
+
+      def on_process(event)
+        @processors[rand(100)].forward!(event)
+      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
+    end
+
+    # Create your processor class.
+    class MyProcessor < Tribe::Actor
+      private
+      def initialize(options = {})
+        super
+      end
 
-    actor_a.enqueue(:shutdown)
-    actor_b.enqueue(:shutdown)
+      def on_process(event)
+        puts "MyProcessor (#{identifier}) received a process event (#{event.inspect})."
+      end
 
-#### Futures and Performance
+      def exception_handler(e)
+        super
+        puts concat_e("MyProcessor (#{identifier}) died.", e)
+      end
 
-Futures have overhead associated with them.
-You should avoid them unless you are actaully interested in the result.
+      def shutdown_handler(event)
+        super
+        puts "MyProcessor (#{identifier}) is shutting down.  Put cleanup code here."
+      end
+    end
 
-You should also prefer non-blocking futures over blocking ones.
-This is because a blocking future causes the current actor (and thread) to sleep.
+    # Create the router.
+    router = MyRouter.new(:name => 'router')
 
-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.
+    # Send an event to the router and it will forward it to a random processor.
+    100.times do |i|
+      router.message!(:process, i)
+    end
 
-If you choose to use blocking 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.
+    # Shutdown the router.
+    router.shutdown!
 
 ## TODO - missing features
 
 - Supervisors.
 - Linking.
 - Future timeouts.
-- Clustering.
+- Remote actors (Tribe clustering).
 
 ## Contributing
 

data/lib/tribe/actable.rb

@@ -32,27 +32,32 @@ module Tribe
     # 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.
+    #        Methods with a ! are designed for asynchronous communication.
     #
 
     public
 
-    def enqueue(command, data = nil)
-      return false unless alive?
+    def message!(command, data = nil)
+      return forward!(Workers::Event.new(command, data))
+    end
+
+    def forward!(event)
+      return nil unless alive?
 
-      @_as.mailbox.push(Workers::Event.new(command, data)) do
+      @_as.mailbox.push(event) do
         @_as.pool.perform { process_events }
       end
 
-      return true
+      return nil
     end
 
-    def enqueue_future(command, data = nil)
+    def future!(command, data = nil)
       @_as.futures ||= Tribe::SafeSet.new # Lazy instantiation for performance.
 
       future = Tribe::Future.new
       @_as.futures.add(future)
 
-      perform do
+      perform! do
         begin
           result = event_handler(Workers::Event.new(command, data))
           future.result = result
@@ -67,6 +72,14 @@ module Tribe
       return future
     end
 
+    def shutdown!
+      return message!(:shutdown)
+    end
+
+    def perform!(&block)
+      return message!(:perform, block)
+    end
+
     def alive?
       @_as.mailbox.synchronize { return @_as.alive }
     end
@@ -79,14 +92,6 @@ module Tribe
       return @_as.name ? "#{object_id}:#{@_as.name}" : object_id
     end
 
-    def shutdown
-      return enqueue(:shutdown)
-    end
-
-    def perform(&block)
-      return enqueue(:perform, block)
-    end
-
     #
     # Private event handlers.
     # Notes: These methods are designed to be overriden (make sure you call super).
@@ -145,7 +150,7 @@ module Tribe
 
       timer = Workers::Timer.new(delay, :scheduler => @_as.scheduler) do
         @_as.timers.delete(timer)
-        enqueue(command, data)
+        message!(command, data)
       end
 
       @_as.timers.add(timer)
@@ -159,7 +164,7 @@ module Tribe
       @_as.timers ||= Tribe::SafeSet.new
 
       timer = Workers::PeriodicTimer.new(delay, :scheduler => @_as.scheduler) do
-        enqueue(command, data)
+        message!(command, data)
         unless alive?
           @_as.timers.delete(timer)
           timer.cancel

data/lib/tribe/version.rb

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

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: tribe
 version: !ruby/object:Gem::Version
-  version: 0.2.3
-  prerelease: 
+  version: 0.3.0
 platform: ruby
 authors:
 - Chad Remesch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-04 00:00:00.000000000 Z
+date: 2013-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: workers
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - '='
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - '='
       - !ruby/object:Gem::Version
@@ -54,27 +51,26 @@ files:
 - tribe.gemspec
 homepage: https://github.com/chadrem/tribe
 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.25
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: 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.