tribe 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c286bf55aac4e1e85558bb56a3b49b2e84dcabc3
-  data.tar.gz: 1b0743b0e63db87ae6d0b0f81bacdd12c520ba46
+  metadata.gz: 50de6f25aa1a85a300729b25e432f661619f2468
+  data.tar.gz: d8f1c9329ceefad25909e6db346288a6aea39ab6
 SHA512:
-  metadata.gz: a87e8def58e14e31d464783f10c30c421ef0c8343b1a0abb8bc9075c73208ba32e28cc3d195dda7ffee0daa80072e16d2397392e5997810a51f57b35058a2673
-  data.tar.gz: bb336feb72e68638ad1d92b63826724ea07eb768f377eaa53a01639ba801a876adf5f80588067246922490482572913f5fd0e8478fe5ecca4406e476db00b364
+  metadata.gz: 9f58370c1c6b6b9ba42b7858bcac28016f4a5dc170432d7882163573330c12b949ad037daa36424db3839d8dad7f642294302be4d91903ea80f431ee4a9a721a
+  data.tar.gz: d894eb6eca95825d89ab91d4823545fa737a6cc588320ffb80b3f4239e5a3c946e13191f3941210b5f2f0436e2dc22692c2532d3646563452790a4edf6588f9a

data/README.md

@@ -9,6 +9,23 @@ It is built on top of the [Workers] (https://github.com/chadrem/workers "Workers
 
 Event-driven servers can be built using [Tribe EM] (https://github.com/chadrem/tribe_em "Tribe EM").
 
+## Contents
+
+- [Installation](#installation)
+- [Actors](#actors)
+- [Registries](#registries)
+- [Timers](#timers)
+- [Futures](#futures)
+  - [Non-blocking](#non-blocking)
+  - [Blocking](#blocking)
+  - [Timeouts](#timeouts)
+  - [Performance](#performance-summary)
+- [Forwarding](#forwarding)
+- [Linking](#linking)
+- [Supervisors](#supervisors)
+- [Benchmarks](#benchmarks)
+- [Contributing](#contributing)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -29,7 +46,7 @@ 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.
+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.
@@ -46,10 +63,12 @@ More information on them will be provided throughout this readme.
       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
@@ -82,7 +101,8 @@ Actors that block for long periods of time should use a dedicated thread (:dedic
       :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).
+      :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
@@ -124,7 +144,7 @@ Both one-shot and periodic timers are provided.
     end
 
     # Sleep in order to observe the timers.
-    sleep 10
+    sleep(10)
 
     # Shutdown the actors.
     10.times do |i|
@@ -147,6 +167,7 @@ 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
 
@@ -171,6 +192,7 @@ 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
 
@@ -204,6 +226,7 @@ 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
 
@@ -224,6 +247,7 @@ 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
 
@@ -245,6 +269,23 @@ The actor won't process any other events until the future has a result.
     actor_a.shutdown!
     actor_b.shutdown!
 
+#### Timeouts
+
+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).
+    future = Tribe::Future.new
+
+    # Set a timeout (in seconds).
+    future.timeout = 2
+
+    # Wait for the timeout.
+    sleep(3)
+
+    # The result of the future is a timeout exception.
+    puts "Result: #{future.result}"
+
 #### Performance Summary
 
 Below you will find a summary of performance recommendations regarding the use of futures:
@@ -271,10 +312,12 @@ This lets you build routers that delegate work to other actors.
       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
@@ -288,10 +331,12 @@ This lets you build routers that delegate work to other actors.
       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
@@ -307,16 +352,110 @@ This lets you build routers that delegate work to other actors.
     # Shutdown the router.
     router.shutdown!
 
-## Benchmarks
+## Linking
 
-  Please see the [performance] (https://github.com/chadrem/tribe/wiki/Performance "performance") wiki page for more information.
+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.
+
+    # Create the root level actor class.
+    class Level1 < Tribe::Actor
+      private
+      def on_spawn(event)
+        5.times do |i|
+          name = "level2_#{i}"
+          puts name
+          actor = spawn(Level2, :name => name)
+          actor.message!(:spawn, i)
+        end
+      end
+    end
+
+    # Create the mid-level actor class.
+    class Level2 < Tribe::Actor
+      private
+      def on_spawn(event)
+        5.times do |i|
+          name = "level3_#{event.data}_#{i}"
+          actor = spawn(Level3, :name => name)
+          actor.message!(:spawn)
+        end
+      end
+    end
+
+    # Create the bottom level actor class.
+    class Level3 < Tribe::Actor
+      private
+      def on_spawn(event)
+        puts "#{identifier} hello world!"
+      end
+    end
+
+    # Create the root actor.
+    root = Level1.new(:name => 'level1')
+
+    # Tell the root actor to create the tree of children.
+    root.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.
+
+    # Create the root level actor class.
+    class Level1 < Tribe::Actor
+      private
+      def on_spawn(event)
+        5.times do |i|
+          create_subtree
+        end
+      end
+
+      def create_subtree
+        actor = spawn(Level2)
+        actor.message!(:spawn)
+      end
+
+      def child_died_handler(actor, exception)
+        puts "My child (#{actor.identifier}) died.  Restarting it."
+        create_subtree
+      end
+    end
 
-## TODO - missing features
+    # Create the mid-level actor class.
+    class Level2 < Tribe::Actor
+      private
+      def on_spawn(event)
+        5.times do |i|
+          actor = spawn(Level3)
+          actor.message!(:spawn)
+        end
+      end
+    end
 
-- Supervisors.
-- Linking.
-- Future timeouts.
-- Remote actors (Tribe clustering).
+    # Create the bottom level actor class.
+    class Level3 < Tribe::Actor
+      private
+      def on_spawn(event)
+        puts "#{identifier} says hello world!"
+        raise 'Sometimes I like to die.' if rand < 0.5
+      end
+    end
+
+    # Create the root actor.
+    root = Level1.new(:name => 'root')
+
+    # Tell the root actor to create the tree of children.
+    root.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.
+
+## Benchmarks
+
+  Please see the [performance] (https://github.com/chadrem/tribe/wiki/Performance "performance") wiki page for more information.
 
 ## Contributing
 

data/lib/tribe/actable.rb

@@ -23,6 +23,7 @@ module Tribe
       @_as.registry = options[:registry] || Tribe.registry
       @_as.scheduler = options[:scheduler]
       @_as.name = options[:name]
+      @_as.parent = options[:parent]
 
       @_as.registry.register(self)
     end
@@ -60,11 +61,11 @@ module Tribe
     end
 
     def shutdown!
-      return message!(:shutdown)
+      return message!(:_shutdown)
     end
 
     def perform!(&block)
-      return message!(:perform, block)
+      return message!(:_perform, block)
     end
 
     def alive?
@@ -106,6 +107,16 @@ module Tribe
     end
 
     def exception_handler(exception)
+      if @_as.parent
+        @_as.parent.message!(:_child_died, [self, exception])
+      end
+
+      if @_as.children
+        @_as.children.each { |c| c.message!(:_parent_died, [self, exception]) }
+        @_as.children.clear
+        @_as.children = nil
+      end
+
       return nil
     end
 
@@ -120,14 +131,29 @@ module Tribe
     end
 
     def cleanup_handler(exception = nil)
+      @_as.exception = exception
       @_as.pool.shutdown if @_as.dedicated
       @_as.mailbox.kill
       @_as.registry.unregister(self)
       @_as.timers.each { |t| t.cancel } if @_as.timers
 
+      if @_as.children && exception.nil?
+        @_as.children.each { |c| c.shutdown! }
+        @_as.children.clear
+        @_as.children = nil
+      end
+
       return nil
     end
 
+    def child_died_handler(child, exception)
+      raise Tribe::ActorChildDied.new("#{child.identifier} died.")
+    end
+
+    def parent_died_handler(parent, exception)
+      raise Tribe::ActorParentDied.new("#{parent.identifier} died.")
+    end
+
     #
     # Private API methods.
     # Notes: Use these methods internally in your actor.
@@ -188,20 +214,34 @@ module Tribe
       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)
         case event.command
-        when :shutdown
+        when :_shutdown
           cleanup_handler
           shutdown_handler(event)
-        when :perform
+        when :_perform
           perform_handler(event)
+        when :_child_died
+          child_died_handler(event.data[0], event.data[1])
+        when :_parent_died
+          parent_died_handler(event.data[0], event.data[1])
         else
           event_handler(event)
         end

data/lib/tribe/actor_state.rb

@@ -8,5 +8,8 @@ module Tribe
     attr_accessor :name
     attr_accessor :pool
     attr_accessor :active_event
+    attr_accessor :parent
+    attr_accessor :children
+    attr_accessor :exception
   end
 end

data/lib/tribe/exceptions.rb

@@ -1,8 +1,14 @@
 module Tribe
-  class ActorShutdownError < RuntimeError; end
-  class ActorNameError < RuntimeError; end
+  class TribeError < RuntimeError; end
 
-  class FutureError < RuntimeError; end
+  class ActorShutdownError < TribeError; end
+  class ActorNameError < TribeError; end
+  class ActorChildDied < TribeError; end
+  class ActorParentDied < TribeError; end
 
-  class RegistryError < RuntimeError; end
+  class FutureError < TribeError; end
+  class FutureNoResult < TribeError; end
+  class FutureTimeout < TribeError; end
+
+  class RegistryError < TribeError; end
 end

data/lib/tribe/future.rb

@@ -17,9 +17,17 @@ module Tribe
       end
     end
 
+    def timeout?
+      @mutex.synchronnize do
+        return @state == :finished && @result.is_a?(Tribe::FutureTimeout)
+      end
+    end
+
     def result=(val)
       @mutex.synchronize do
-        raise Tribe::FutureError.new('Result must only be set once.') unless @state == :initialized
+        return unless @state == :initialized
+
+        @timer.cancel if @timer
 
         @result = val
         @state = :finished
@@ -37,7 +45,7 @@ module Tribe
 
     def result
       @mutex.synchronize do
-        raise Tribe::FutureError.new('Result must be set first.') unless @state == :finished
+        raise Tribe::FutureNoResult.new('Result must be set first.') unless @state == :finished
 
         return @result
       end
@@ -55,7 +63,7 @@ module Tribe
 
     def success?
       @mutex.synchronize do
-        raise Tribe::FutureError.new('Result must be set first.') unless @state == :finished
+        raise Tribe::FutureNoResult.new('Result must be set first.') unless @state == :finished
 
         return !@result.is_a?(Exception)
       end
@@ -94,5 +102,24 @@ module Tribe
         return nil
       end
     end
+
+    def timeout
+      @mutex.synchronize do
+      end
+    end
+
+    def timeout=(val)
+      raise Tribe::FutureError.new('Timeout may only be set once.') if @timeout
+
+      @timeout = val
+
+      @timer = Workers::Timer.new(val) do
+        begin
+          raise Tribe::FutureTimeout.new("Timeout after #{@timeout} seconds.")
+        rescue Tribe::FutureTimeout => e
+          self.result = e
+        end
+      end
+    end
   end
 end

data/lib/tribe/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tribe
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Chad Remesch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-09 00:00:00.000000000 Z
+date: 2013-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: workers