tribe 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 50de6f25aa1a85a300729b25e432f661619f2468
-  data.tar.gz: d8f1c9329ceefad25909e6db346288a6aea39ab6
+  metadata.gz: 865a31569730f5bc15800bc24f0dc791faea2971
+  data.tar.gz: c7a793ff5df24f85ddf2d0f877fd5a892f946fe6
 SHA512:
-  metadata.gz: 9f58370c1c6b6b9ba42b7858bcac28016f4a5dc170432d7882163573330c12b949ad037daa36424db3839d8dad7f642294302be4d91903ea80f431ee4a9a721a
-  data.tar.gz: d894eb6eca95825d89ab91d4823545fa737a6cc588320ffb80b3f4239e5a3c946e13191f3941210b5f2f0436e2dc22692c2532d3646563452790a4edf6588f9a
+  metadata.gz: ec0d7842dd09a91e305da5719b19bea9a5aa584edcf39a522036f5668c05fac9efaafb442f8706c6766080b15b69e3f47d6edf778b56443439b2a0b567703ce8
+  data.tar.gz: 28bd5c028b349ac7ed29d45593aae3a888e55d280fa7a927f6d3614e4bd4476c382fce95401ede14e04b2ddd0408b777a0b00fd3630703a2d0ed37ee0c960fb4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    tribe (0.3.2)
+    tribe (0.4.0)
       workers (= 0.2.2)
 
 GEM

data/README.md

@@ -13,6 +13,9 @@ Event-driven servers can be built using [Tribe EM] (https://github.com/chadrem/t
 
 - [Installation](#installation)
 - [Actors](#actors)
+  - [Root](#root-actor)
+  - [Handlers](#handlers)
+  - [Messages](#messages)
 - [Registries](#registries)
 - [Timers](#timers)
 - [Futures](#futures)
@@ -42,18 +45,34 @@ Or install it yourself as:
 
 ## Actors
 
-Actors are light-weight objects that use asynchronous message passing for communcation.
-There are two types of methods that you create in your actors:
+Actors are the building blocks of your application.
+There are three ways to create an actor class:
+
+- Inherit from Tribe::Actor (uses the shared thread pool).
+- Inherit from Tribe::DedicatedActor (uses a dedicated thread).
+- Mixin Tribe::Actable and call the Actable#init_actable method in your constructor.
+
+
+#### Root
+
+Well designed applications built with the actor model tend to organize their actors in a tree like structure.
+To encourage this, Tribe has a special built-in actor known as the root actor.
+You should use this actor to spawn all of your application specific actors.
+
+    Tribe.root
+
+#### Handlers
+
+There are two types of methods that you create in your actor classes:
 
 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 hooks into the Tribe's actor system.
 
-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.
+#### Messages
 
-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.
+Actors communicate asynchronously using a number of methods that end in ! (exclamation point or “bang”).
+The most basic type of communication is a message and they are sent using using the Actable#message! and Actable#deliver_message! methods.
+These methods always return nil since they are fire-and-forget.
 
     # Create your custom actor class.
     class MyActor < Tribe::Actor
@@ -73,15 +92,15 @@ More information on them will be provided throughout this readme.
       end
     end
 
-    # Create some named actors.
+    # Create some named actors that are children of the root actor.
     100.times do |i|
-      MyActor.new(:name => "my_actor_#{i}")
+      Tribe.root.spawn(MyActor, :name => "my_actor_#{i}")
     end
 
     # Send an event to each actor.
     100.times do |i|
       actor = Tribe.registry["my_actor_#{i}"]
-      actor.message!(:my_custom, 'hello world')
+      actor.deliver_message!(:my_custom, 'hello world')
     end
 
     # Shutdown the actors.
@@ -90,27 +109,12 @@ More information on them will be provided throughout this readme.
       actor.shutdown!
     end
 
-#### Implementation
-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).
-
-#### Options (defaults below)
-
-    actor = Tribe::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.
-      :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).
-      :parent => nil                    # Set the parent actor (used by the supervision feature).
-    )
-
 ## 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')
+    actor = Tribe.root.spawn(Tribe::Actor, :name => 'some_actor')
 
     if actor == Tribe.registry['some_actor']
       puts 'Successfully found some_actor in the registry.'
@@ -140,7 +144,7 @@ Both one-shot and periodic timers are provided.
 
     # Create some named actors.
     10.times do |i|
-      MyActor.new(:name => "my_actor_#{i}")
+      Tribe.root.spawn(MyActor, :name => "my_actor_#{i}")
     end
 
     # Sleep in order to observe the timers.
@@ -154,9 +158,9 @@ Both one-shot and periodic timers are provided.
 
 ## Futures
 
-As mentioned above, message passing with the Actable#message! method is asynchronous and always returns nil.
+Message passing with the Actable#message! and Actable#deliver_message! methods is asynchronous and always returns nil.
 This can be a pain since in many cases you will be interested in the result.
-The Actable#future! method solves this problem by returning a Tribe::Future object instead of nil.
+The Actable#future! method solves this problem by returning a Tribe::Future object.
 You can then use this object to obtain the result when it becomes available.
 
 #### Non-blocking
@@ -173,19 +177,14 @@ No waiting for a result is involved and the actor will continue to process other
 
       def on_start(event)
         friend = registry['actor_b']
-
-        future = friend.future!(:compute, 10)
+        future = future!(friend, :compute, 10)
 
         future.success do |result|
-          perform! do
-            puts "ActorA (#{identifier}) future result: #{result}"
-          end
+          puts "ActorA (#{identifier}) future result: #{result}"
         end
 
         future.failure do |exception|
-          perform! do
-            puts "ActorA (#{identifier}) future failure: #{exception}"
-          end
+          puts "ActorA (#{identifier}) future failure: #{exception}"
         end
       end
     end
@@ -206,18 +205,14 @@ No waiting for a result is involved and the actor will continue to process other
       end
     end
 
-    actor_a = ActorA.new(:name => 'actor_a')
-    actor_b = ActorB.new(:name => 'actor_b')
+    actor_a = Tribe.root.spawn(ActorA, :name => 'actor_a')
+    actor_b = Tribe.root.spawn(ActorB, :name => 'actor_b')
 
-    actor_a.message!(:start)
+    actor_a.deliver_message!(:start)
 
     actor_a.shutdown!
     actor_b.shutdown!
 
-*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 unexpected behavior (thread safety will be lost)!
-
 #### Blocking
 
 Blocking futures are synchronous.
@@ -232,8 +227,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.future!(:compute, 10)
+        future = future!(friend, :compute, 10)
 
         future.wait # The current thread will sleep until a result is available.
 
@@ -261,10 +255,10 @@ The actor won't process any other events until the future has a result.
       end
     end
 
-    actor_a = ActorA.new(:name => 'actor_a')
-    actor_b = ActorB.new(:name => 'actor_b')
+    actor_a = Tribe.root.spawn(ActorA, :name => 'actor_a')
+    actor_b = Tribe.root.spawn(ActorB, :name => 'actor_b')
 
-    actor_a.message!(:start)
+    actor_a.deliver_message!(:start)
 
     actor_a.shutdown!
     actor_b.shutdown!
@@ -274,7 +268,7 @@ The actor won't process any other events until the future has a result.
 Futures can be confgured to timeout after a specified number of seconds.
 When a timeout occurs, the result of the future will be a Tribe::FutureTimeout exception.
 
-    # Manually create a future (Use Actable#future! in your actors).
+    # Manually create a future for this example (Use Actable#future! in your actors).
     future = Tribe::Future.new
 
     # Set a timeout (in seconds).
@@ -342,11 +336,11 @@ This lets you build routers that delegate work to other actors.
     end
 
     # Create the router.
-    router = MyRouter.new(:name => 'router')
+    router = Tribe.root.spawn(MyRouter, :name => 'router')
 
     # Send an event to the router and it will forward it to a random processor.
     100.times do |i|
-      router.message!(:process, i)
+      router.deliver_message!(:process, i)
     end
 
     # Shutdown the router.
@@ -355,11 +349,12 @@ This lets you build routers that delegate work to other actors.
 ## Linking
 
 Linking allows actors to group together into a tree structure such that they all live or die as one group.
-Such linking is useful for breaking complex problems into smaller (and easier to manage) components.
-To create a linked actor you use the Actable#spawn method to create it.
-If any actor in a tree of linked actors dies, it will cause all actors above and below it to die too.
+Such linking is useful for breaking up complex problems into multiple smaller units.
+To create a linked actor you use the Actable#spawn method.
+By default, if a linked actor dies, it will cause its parent and children to die too.
+Thus the entire tree lives or dies together.
 
-    # Create the root level actor class.
+    # Create the top-level actor class.
     class Level1 < Tribe::Actor
       private
       def on_spawn(event)
@@ -367,7 +362,7 @@ If any actor in a tree of linked actors dies, it will cause all actors above and
           name = "level2_#{i}"
           puts name
           actor = spawn(Level2, :name => name)
-          actor.message!(:spawn, i)
+          message!(actor, :spawn, i)
         end
       end
     end
@@ -379,7 +374,7 @@ If any actor in a tree of linked actors dies, it will cause all actors above and
         5.times do |i|
           name = "level3_#{event.data}_#{i}"
           actor = spawn(Level3, :name => name)
-          actor.message!(:spawn)
+          message!(actor, :spawn)
         end
       end
     end
@@ -392,18 +387,19 @@ If any actor in a tree of linked actors dies, it will cause all actors above and
       end
     end
 
-    # Create the root actor.
-    root = Level1.new(:name => 'level1')
+    # Create the top-level actor.
+    top = Tribe.root.spawn(Level1, :name => 'level1')
 
     # Tell the root actor to create the tree of children.
-    root.message!(:spawn)
+    top.deliver_message!(:spawn)
 
 ## Supervisors
 
-As mentioned above, a failure in a linked actor will cause all associated actors (parent and children) to die.
-Supervisors can be used to block the failure from propogating and allow you to restart the failed section of the tree.
+A failure in a linked actor will cause all associated actors (parent and children) to die.
+Supervisors can be used to block the failure from propogating.
+You then have the option to re-create the failed actor.
 
-    # Create the root level actor class.
+    # Create the top-level actor class.
     class Level1 < Tribe::Actor
       private
       def on_spawn(event)
@@ -414,7 +410,7 @@ Supervisors can be used to block the failure from propogating and allow you to r
 
       def create_subtree
         actor = spawn(Level2)
-        actor.message!(:spawn)
+        message!(actor, :spawn)
       end
 
       def child_died_handler(actor, exception)
@@ -429,7 +425,7 @@ Supervisors can be used to block the failure from propogating and allow you to r
       def on_spawn(event)
         5.times do |i|
           actor = spawn(Level3)
-          actor.message!(:spawn)
+          message!(actor, :spawn)
         end
       end
     end
@@ -443,13 +439,14 @@ Supervisors can be used to block the failure from propogating and allow you to r
       end
     end
 
-    # Create the root actor.
-    root = Level1.new(:name => 'root')
+    # Create the top-level actor.
+    top = Tribe.root.spawn(Level1, :name => 'root')
 
-    # Tell the root actor to create the tree of children.
-    root.message!(:spawn)
+    # Tell the top-level actor to create the tree of children.
+    top.deliver_message!(:spawn)
 
 #### Important!
+
 Restarting named actors is NOT currently supported, but will be in a future update.
 Attempting to do so may result in Tribe::RegistryError exceptions when trying to spawn a replacement child.
 

data/lib/tribe/actable.rb

@@ -37,35 +37,64 @@ module Tribe
 
     public
 
-    def event!(event)
-      push_event(event)
+    def deliver_event!(event)
+      @_as.mailbox.push(event) do
+        process_events
+      end
+
+      return nil
+    end
+
+    def deliver_message!(command, data = nil, src = nil)
+      deliver_event!(Tribe::Event.new(command, data, src))
 
       return nil
     end
 
-    def message!(command, data = nil, source = nil)
-      event = Tribe::Event.new(command, data, source)
+    def message!(dest, command, data = nil)
+      event = Tribe::Event.new(command, data, self)
 
-      push_event(event)
+      dest.deliver_event!(event)
 
       return nil
     end
 
-    def future!(command, data = nil, source = nil)
-      event = Tribe::Event.new(command, data, source)
-      event.future = future = Tribe::Future.new
+    def future!(dest, command, data = nil)
+      event = Tribe::Event.new(command, data, self)
+      event.future = future = Tribe::Future.new(self)
 
-      push_event(event)
+      dest.deliver_event!(event)
 
       return future
     end
 
     def shutdown!
-      return message!(:_shutdown)
+      return deliver_message!(:_shutdown)
     end
 
     def perform!(&block)
-      return message!(:_perform, block)
+      return deliver_message!(:_perform, block)
+    end
+
+    def spawn(klass, actor_options = {}, spawn_options = {})
+      actor_options[:parent] = self
+
+      @_as.children ||= []
+      child = nil
+
+      if spawn_options[:no_raise_on_failure]
+        begin
+          child = klass.new(actor_options)
+        rescue Exception => e
+          return false
+        end
+      else
+        child = klass.new(actor_options)
+      end
+
+      @_as.children << child
+
+      return child
     end
 
     def alive?
@@ -108,11 +137,11 @@ module Tribe
 
     def exception_handler(exception)
       if @_as.parent
-        @_as.parent.message!(:_child_died, [self, exception])
+        @_as.parent.deliver_message!(:_child_died, [self, exception])
       end
 
       if @_as.children
-        @_as.children.each { |c| c.message!(:_parent_died, [self, exception]) }
+        @_as.children.each { |c| c.deliver_message!(:_parent_died, [self, exception]) }
         @_as.children.clear
         @_as.children = nil
       end
@@ -176,7 +205,7 @@ module Tribe
 
       timer = Workers::Timer.new(delay, :scheduler => @_as.scheduler) do
         @_as.timers.delete(timer)
-        message!(command, data)
+        deliver_message!(command, data)
       end
 
       @_as.timers.add(timer)
@@ -190,7 +219,7 @@ module Tribe
       @_as.timers ||= Tribe::SafeSet.new
 
       timer = Workers::PeriodicTimer.new(delay, :scheduler => @_as.scheduler) do
-        message!(command, data)
+        deliver_message!(command, data)
         unless alive?
           @_as.timers.delete(timer)
           timer.cancel
@@ -208,27 +237,12 @@ module Tribe
     #
 
     def forward!(dest)
-      dest.event!(@_as.active_event)
+      dest.deliver_event!(@_as.active_event)
       @_as.active_event = nil
 
       return nil
     end
 
-    def spawn(klass, options = {})
-      options[:parent] = self
-
-      @_as.children ||= []
-      @_as.children << (actor = klass.new(options))
-
-      return actor
-    end
-
-    def push_event(event)
-      @_as.mailbox.push(event) do
-        process_events
-      end
-    end
-
     # All system commands are prefixed with an underscore.
     def process_events
       while (event = @_as.mailbox.obtain_and_shift)

data/lib/tribe/future.rb

@@ -1,12 +1,13 @@
 module Tribe
   class Future
-    def initialize
+    def initialize(actor = nil)
       @state = :initialized
       @mutex = Mutex.new
       @condition = ConditionVariable.new
       @result = nil
       @success_callback = nil
       @failure_callback = nil
+      @actor = actor
 
       return nil
     end
@@ -34,9 +35,25 @@ module Tribe
         @condition.signal
 
         if val.is_a?(Exception)
-          @failure_callback.call(val) if @failure_callback
+          if @failure_callback
+            if @actor
+              @actor.perform! do
+                @failure_callback.call(val)
+              end
+            else
+              @failure_callback.call(val)
+            end
+          end
         else
-          @success_callback.call(val) if @success_callback
+          if @success_callback
+            if @actor
+              @actor.perform! do
+                @success_callback.call(val)
+              end
+            else
+              @success_callback.call(val)
+            end
+          end
         end
 
         return nil
@@ -79,7 +96,15 @@ module Tribe
         when :initialized
           @success_callback = block
         when :finished
-          yield(@result) unless @result.is_a?(Exception)
+          unless @result.is_a?(Exception)
+            if @actor
+              @actor.perform! do
+                block.call(@result)
+              end
+            else
+              block.call(@result)
+            end
+          end
         else
           raise Tribe::FutureError.new('Invalid state.')
         end
@@ -94,7 +119,15 @@ module Tribe
         when :initialized
           @failure_callback = block
         when :finished
-          yield(@result) if @result.is_a?(Exception)
+          if @result.is_a?(Exception)
+            if @actor
+              @actor.perform! do
+                block.call(@result)
+              end
+            else
+              block.call(@result)
+            end
+          end
         else
           raise Tribe::FutureError.new('Invalid state.')
         end

data/lib/tribe/root.rb

@@ -0,0 +1,19 @@
+module Tribe
+  class Root < Tribe::Actor
+    private
+
+    def initialize(options = {})
+      unless options[:permit_root]
+        raise 'Application code should never create the root actor.'
+      end
+
+      options.delete(:permit_root)
+
+      super
+    end
+
+    def child_died_handler(child, exception)
+      # Let the children die silently since the root actor should live forever.
+    end
+  end
+end

data/lib/tribe/version.rb

@@ -1,3 +1,3 @@
 module Tribe
-  VERSION = '0.3.2'
+  VERSION = '0.4.0'
 end

data/lib/tribe.rb

@@ -12,6 +12,7 @@ require 'tribe/actor'
 require 'tribe/dedicated_actor'
 require 'tribe/registry'
 require 'tribe/future'
+require 'tribe/root'
 
 module Tribe
   def self.registry
@@ -22,7 +23,12 @@ module Tribe
     @registry.dispose if @registry
     @registry = val
   end
+
+  def self.root
+    @root ||= Tribe::Root.new(:name => 'root', :permit_root => true)
+  end
 end
 
-# Force initialization of defaults.
+# Force initialization.
 Tribe.registry
+Tribe.root

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tribe
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Chad Remesch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-11 00:00:00.000000000 Z
+date: 2013-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: workers
@@ -49,6 +49,7 @@ files:
 - lib/tribe/future.rb
 - lib/tribe/mailbox.rb
 - lib/tribe/registry.rb
+- lib/tribe/root.rb
 - lib/tribe/safe_set.rb
 - lib/tribe/version.rb
 - tribe.gemspec