tribe 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 865a31569730f5bc15800bc24f0dc791faea2971
-  data.tar.gz: c7a793ff5df24f85ddf2d0f877fd5a892f946fe6
+  metadata.gz: f3bf6bd1aba1fc0bc7778e35002942f86a23160e
+  data.tar.gz: c8b4d5c3c3e28f2d3b0598f257a6769ee7e8708b
 SHA512:
-  metadata.gz: ec0d7842dd09a91e305da5719b19bea9a5aa584edcf39a522036f5668c05fac9efaafb442f8706c6766080b15b69e3f47d6edf778b56443439b2a0b567703ce8
-  data.tar.gz: 28bd5c028b349ac7ed29d45593aae3a888e55d280fa7a927f6d3614e4bd4476c382fce95401ede14e04b2ddd0408b777a0b00fd3630703a2d0ed37ee0c960fb4
+  metadata.gz: 83ac8698abdc2012668474d87009d14156a0a8ef82c17553475f47284a427390bedba8c32f91260da9a14075e28602dfa2e07fe967edbf3963e85748d6b2e50a
+  data.tar.gz: 269e3611a89686367ed6f012af21eb0fd5ba49a0d9e722b2cd01ecd7025f74158d02484a10d951eebde217ab8e36f8b8731979221fcd8fe25382ed0aca65875c

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.ruby-version

@@ -0,0 +1 @@
+2.2.2

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.5

data/Gemfile

@@ -1,4 +1,7 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in tribe.gemspec
+gem 'coveralls', :require => false
+
 gemspec
+
+gem 'workers', :git => 'https://github.com/chadrem/workers.git'

data/README.md

@@ -1,31 +1,30 @@
-# Tribe
+# Tribe [![Build Status](https://travis-ci.org/chadrem/tribe.svg)](https://travis-ci.org/chadrem/tribe) [![Coverage Status](https://coveralls.io/repos/chadrem/tribe/badge.svg?branch=master&service=github)](https://coveralls.io/github/chadrem/tribe?branch=master)
 
-Tribe is a Ruby gem that implements event-driven [actors] (http://en.wikipedia.org/wiki/Actor_model "actors").
-Actors are lightweight concurrent objects that use asynchronous message passing for communication.
+Tribe is a Ruby gem that implements the [actor model] (http://en.wikipedia.org/wiki/Actor_model "actors") in an event-driven way.
 
 Tribe focuses on high performance, low latency, a simple API, and flexibility.
 It's goal is to support at least one million actors running on a small group of threads.
 It is built on top of the [Workers] (https://github.com/chadrem/workers "Workers") gem.
 
-Event-driven servers can be built using [Tribe EM] (https://github.com/chadrem/tribe_em "Tribe EM").
-
 ## Contents
 
 - [Installation](#installation)
 - [Actors](#actors)
-  - [Root](#root-actor)
+  - [Root](#root)
   - [Handlers](#handlers)
-  - [Messages](#messages)
+- [Messages](#messages)
 - [Registries](#registries)
-- [Timers](#timers)
 - [Futures](#futures)
   - [Non-blocking](#non-blocking)
   - [Blocking](#blocking)
   - [Timeouts](#timeouts)
   - [Performance](#performance-summary)
 - [Forwarding](#forwarding)
+- [Timers](#timers)
 - [Linking](#linking)
 - [Supervisors](#supervisors)
+- [Blocking code](#blocking-code)
+- [Debugging](#debugging)
 - [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
 
@@ -48,31 +47,51 @@ Or install it yourself as:
 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.
-
+- Inherit from ````Tribe::Actor```` (uses the shared thread pool).
+- Inherit from ````Tribe::DedicatedActor```` (uses a dedicated thread).
+- Mixin ````Tribe::Actable```` and call the ````init_actable```` in your constructor.
 
 #### Root
 
-Well designed applications built with the actor model tend to organize their actors in a tree like structure.
+A well designed application organizes its 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.
+You should use the root actor to spawn all of your application specific actors.
+
+    class MyActor < Tribe::Actor
+      private
+      # Your code goes here.
+    end
+
+    Tribe.root.spawn!(MyActor)
+
+#### Command Handlers
+
+Command handlers are how you customize your actors.
+They are private methods that are prefixed with "on_" and they define the commands your actor knows how to handle.
+They accept one argument, an instance of ````Tribe::Event```` that shouuld always be named ````event````.
 
-    Tribe.root
+A few command handlers are built into every actor to handle system specific events.  They are:
 
-#### Handlers
+- ````on_initialize````: This handler takes the place of Ruby's ````initialize````.  It is the first event processsed by all actors.
+- ````on_exception````: This handler will be called whenever an exception occurs.  You can access the exception through ````event.data```` in case you want to print it, log it, etc.  An exception inside of an actor will result in that actor's death.
+- ````on_shutdown````: This handler will be called whenever an actor is asked to shutdown cleanly.
+- ````on_child_died````: This handler gives an actor a chance to spawn a replacement child.  You can access a reference to the child through ````event.data````.  If the actor is a supervisor, it will continue to live otherwise it will die too.
+- ````on_child_shutdown````: This handler is similar to ````on_child_died````, but for when a child is shutdown cleanly.
+- ````on_parent_died````: This handler is also similar to ````on_child_died```` except for the parent actor.  Child actors die when their parent dies.
 
-There are two types of methods that you create in your actor classes:
+You should never call the built in command handlers yourself.
+They are reserved for the actor system and calling them yourself could result in unexpected behavior.
 
-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.
+## Messages
 
-#### Messages
+Messages are the most basic type of communication.  They are sent using using two methods:
 
-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.
+- ````message!````: This method is used to tell one actor to send another actor a message.  A reference to the source actor is included in the message in case the destination actor wants to respond.  Usually it is used when your actor code wants to message another actor.
+- ````direct_message!````: This method is used to directly message an actor.  Usually it is used when non-actor code wants to message an actor.  No source actor is associated with the message.
+
+Since messages are fire-and-forget, both of the above methods always return ````nil````.
+
+Messages can include data that you want to pass between actors.  It is best practice to treat data as owned by only one actor at a time.  By doing this, you prevent race conditions and the need to create locks for your data.
 
     # Create your custom actor class.
     class MyActor < Tribe::Actor
@@ -81,26 +100,20 @@ These methods always return nil since they are fire-and-forget.
         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."
+      def on_shutdown(event)
+        puts "MyActor (#{identifier}) is shutting down."
       end
     end
 
     # Create some named actors that are children of the root actor.
     100.times do |i|
-      Tribe.root.spawn(MyActor, :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.deliver_message!(:my_custom, 'hello world')
+      actor.direct_message!(:my_custom, 'hello world')
     end
 
     # Shutdown the actors.
@@ -112,69 +125,29 @@ These methods always return nil since they are fire-and-forget.
 ## 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).
+You don't have to create your own since there is a global one called ````Tribe.registry````.
+The Root actor is named 'root' and stored in the default registry.
 
-    actor = Tribe.root.spawn(Tribe::Actor, :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.'
     end
 
-## Timers
-
-Actors can create timers to perform some work in the future.
-Both one-shot and periodic timers are provided.
-
-    class MyActor < Tribe::Actor
-      private
-      def initialize(options = {})
-        super
-        timer(1, :timer, Time.now)
-        periodic_timer(1, :periodic_timer, Time.now)
-      end
-
-      def on_timer(event)
-        puts "MyActor (#{identifier}) ONE-SHOT: #{event.data}"
-      end
-
-      def on_periodic_timer(event)
-        puts "MyActor (#{identifier}) PERIODIC: #{event.data}"
-      end
-    end
-
-    # Create some named actors.
-    10.times do |i|
-      Tribe.root.spawn(MyActor, :name => "my_actor_#{i}")
-    end
-
-    # Sleep in order to observe the timers.
-    sleep(10)
-
-    # Shutdown the actors.
-    10.times do |i|
-      actor = Tribe.registry["my_actor_#{i}"]
-      actor.shutdown!
-    end
-
 ## Futures
 
-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.
-You can then use this object to obtain the result when it becomes available.
+Messages are limited in that they are one way (fire-and-forget).
+Many times you'll be interested in receiving a response and this is when futures become useful.
+To send a future you use ````future!```` instead of ````message!````.
+It will return a ````Future```` object (instead of ````nil````) that will give you access to the result when it becomes available.
 
-#### Non-blocking
+#### Non-blocking API
 
 Non-blocking futures are asynchronous and use callbacks.
 No waiting for a result is involved and 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 = future!(friend, :compute, 10)
@@ -182,19 +155,18 @@ No waiting for a result is involved and the actor will continue to process other
         future.success do |result|
           puts "ActorA (#{identifier}) future result: #{result}"
         end
+      end
 
-        future.failure do |exception|
-          puts "ActorA (#{identifier}) future failure: #{exception}"
-        end
+      def on_shutdown(event)
+        puts "MyActor (#{identifier}) is shutting down."
       end
     end
 
     class ActorB < Tribe::Actor
-      def exception_handler(e)
-        super
-        puts concat_e("ActorB (#{identifier}) died.", e)
+    private
+      def on_shutdown(event)
+        puts "MyActor (#{identifier}) is shutting down."
       end
-
       def on_compute(event)
         return factorial(event.data)
       end
@@ -205,31 +177,28 @@ No waiting for a result is involved and the actor will continue to process other
       end
     end
 
-    actor_a = Tribe.root.spawn(ActorA, :name => 'actor_a')
-    actor_b = Tribe.root.spawn(ActorB, :name => 'actor_b')
+    actor_a = Tribe.root.spawn!(ActorA, :name => 'actor_a')
+    actor_b = Tribe.root.spawn!(ActorB, :name => 'actor_b')
 
-    actor_a.deliver_message!(:start)
+    actor_a.direct_message!(:start)
 
+    # Shutdown the actors.
+    sleep(3)
     actor_a.shutdown!
     actor_b.shutdown!
 
-#### Blocking
+#### Blocking API
 
 Blocking futures 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 = future!(friend, :compute, 10)
 
-        future.wait # The current thread will sleep until a result is available.
+        wait!(future) # The current thread will sleep until a result is available.
 
         if future.success?
           puts "ActorA (#{identifier}) future result: #{future.result}"
@@ -240,11 +209,7 @@ The actor won't process any other events until the future has a result.
     end
 
     class ActorB < Tribe::Actor
-      def exception_handler(e)
-        super
-        puts concat_e("ActorB (#{identifier}) died.", e)
-      end
-
+    private
       def on_compute(event)
         return factorial(event.data)
       end
@@ -255,10 +220,12 @@ The actor won't process any other events until the future has a result.
       end
     end
 
-    actor_a = Tribe.root.spawn(ActorA, :name => 'actor_a')
-    actor_b = Tribe.root.spawn(ActorB, :name => 'actor_b')
+    actor_a = Tribe.root.spawn!(ActorA, :name => 'actor_a')
+    actor_b = Tribe.root.spawn!(ActorB, :name => 'actor_b')
 
-    actor_a.deliver_message!(:start)
+    actor_a.direct_message!(:start)
+
+    sleep(3)
 
     actor_a.shutdown!
     actor_b.shutdown!
@@ -266,27 +233,50 @@ The actor won't process any other events until the future has a result.
 #### 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.
+When a timeout occurs, the result of the future will be a ````Tribe::FutureTimeout```` exception.
 
-    # Manually create a future for this example (Use Actable#future! in your actors).
-    future = Tribe::Future.new
+    class ActorA < Tribe::Actor
+    private
+      def on_start(event)
+        friend = registry['actor_b']
+        future = future!(friend, :compute, 10)
+        future.timeout = 2
 
-    # Set a timeout (in seconds).
-    future.timeout = 2
+        wait!(future) # The current thread will sleep until a result is available.
 
-    # Wait for the timeout.
-    sleep(3)
+        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
+    private
+      def on_compute(event)
+        sleep(4) # Force a timeout.
+        return event.data * 2
+      end
+    end
+
+    actor_a = Tribe.root.spawn!(ActorA, :name => 'actor_a')
+    actor_b = Tribe.root.spawn!(ActorB, :name => 'actor_b')
 
-    # The result of the future is a timeout exception.
-    puts "Result: #{future.result}"
+    actor_a.direct_message!(:start)
+
+    sleep(6)
+
+    actor_a.shutdown!
+    actor_b.shutdown!
 
 #### Performance Summary
 
-Below you will find a summary of performance recommendations regarding the use of futures:
+Below you will find a summary of performance recommendations for 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.
+- Use ````message!```` unless you really need ````future!```` since futures have overhead.
+- If you use ````future!````, prefer the non-blocking API over the blocking one.
+- If you use ````future!```` with the blocking API, the actor calling ````wait!```` will create a temporary thread.  Since threads are a a finite resource, you should be careful to not create more of them than your operating system can simultaneously support.  There is no such concern with the non-blocking API.
 
 ## Forwarding
 
@@ -296,25 +286,13 @@ This lets you build routers 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 }
+      def on_initialize(event)
+        @processors = 100.times.map { spawn!(MyProcessor) }
       end
 
       def on_process(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
     end
 
     # Create your processor class.
@@ -323,141 +301,194 @@ This lets you build routers that delegate work to other actors.
       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
 
     # Create the router.
-    router = Tribe.root.spawn(MyRouter, :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.deliver_message!(:process, i)
+      router.direct_message!(:process, i)
     end
 
     # Shutdown the router.
+    sleep(3)
     router.shutdown!
 
-## Linking
+## Timers
 
-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 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.
+Actors can create timers to perform some work in the future.
+Both one-shot and periodic timers are provided.
 
-    # Create the top-level actor class.
-    class Level1 < Tribe::Actor
+    class MyActor < Tribe::Actor
       private
-      def on_spawn(event)
-        5.times do |i|
-          name = "level2_#{i}"
-          puts name
-          actor = spawn(Level2, :name => name)
-          message!(actor, :spawn, i)
-        end
+      def on_initialize(event)
+        timer!(1, :timer, 'hello once')
+        periodic_timer!(1, :periodic_timer, 'hello many times')
       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)
-          message!(actor, :spawn)
-        end
+      def on_timer(event)
+        puts "MyActor (#{identifier}) ONE-SHOT: #{event.data}"
       end
-    end
 
-    # Create the bottom level actor class.
-    class Level3 < Tribe::Actor
-      private
-      def on_spawn(event)
-        puts "#{identifier} hello world!"
+      def on_periodic_timer(event)
+        puts "MyActor (#{identifier}) PERIODIC: #{event.data}"
       end
     end
 
-    # Create the top-level actor.
-    top = Tribe.root.spawn(Level1, :name => 'level1')
+    # Create some named actors.
+    10.times do |i|
+      Tribe.root.spawn!(MyActor, :name => "my_actor_#{i}")
+    end
+
+    # Sleep in order to observe the timers.
+    sleep(10)
+
+    # Shutdown the actors.
+    10.times do |i|
+      actor = Tribe.registry["my_actor_#{i}"]
+      actor.shutdown!
+    end
+
+## Linking
+
+Linking allows actors to group together so that they all live or die together.
+Such linking is useful for breaking up complex problems into multiple smaller units.
+To create a linked actor you use the ````spawn!```` method.
+By default, if a linked actor dies, it will cause its parent and children to die too.
+You an override this behavior by using supervisors.
 
-    # Tell the root actor to create the tree of children.
-    top.deliver_message!(:spawn)
+    # Create some linked actors.
+    top = Tribe::Actor.new
+    middle = top.spawn!(Tribe::Actor)
+    bottom = middle.spawn!(Tribe::Actor)
+
+    # Force an exception on the middle actor (it has a parent and a child).
+    middle.perform! { raise 'uh oh' }
+    
+    # Wait.
+    sleep(3)
+    
+    # All actors died together.
+    puts "Top: #{top.alive?}: #{top.exception.class}"
+    puts "Middle: #{middle.alive?}: #{middle.exception.class}"
+    puts "Bottom: #{bottom.alive?}: #{bottom.exception.class}"
 
 ## Supervisors
 
 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.
+You then have the option to re-spawn the failed actor.
+They are created by passing ````{:supervise => true}```` as a third argument to ````spawn!````.
+You can then detect dead children by overriding ````on_child_died````.
+
+    # Create some linked actors.
+    top = Tribe::Actor.new
+    middle = top.spawn!(Tribe::Actor, {}, {:supervise => true})
+    bottom = middle.spawn!(Tribe::Actor)
+
+    # Force an exception on the middle actor (it has a parent and a child).
+    middle.perform! { raise 'uh oh' }
+    
+    # Wait.
+    sleep(3)
+    
+    # Top actor lives because it's a supervisor.  The other two die.
+    puts "Top: #{top.alive?}: #{top.exception.class}"
+    puts "Middle: #{middle.alive?}: #{middle.exception.class}"
+    puts "Bottom: #{bottom.alive?}: #{bottom.exception.class}"
 
-    # Create the top-level actor class.
-    class Level1 < Tribe::Actor
-      private
-      def on_spawn(event)
-        5.times do |i|
-          create_subtree
-        end
-      end
+#### Logging exceptions
 
-      def create_subtree
-        actor = spawn(Level2)
-        message!(actor, :spawn)
-      end
+It is common practice to log actor exceptions or print them to stdout.
+This is easily accomplished with the ````on_exception```` handler in a base class:
 
-      def child_died_handler(actor, exception)
-        puts "My child (#{actor.identifier}) died.  Restarting it."
-        create_subtree
+    class MyBaseActor < Tribe::Actor
+    private
+      def on_exception(event)
+        e = event.data[:exception]
+        puts "#{e.class.name}: #{e.message}:\n#{e.backtrace.join("\n")}"
       end
     end
 
-    # Create the mid-level actor class.
-    class Level2 < Tribe::Actor
-      private
-      def on_spawn(event)
-        5.times do |i|
-          actor = spawn(Level3)
-          message!(actor, :spawn)
+    class CustomActor < MyBaseActor
+    end
+
+    actor = Tribe.root.spawn!(CustomActor)
+    actor.perform! { raise 'goodbye' }
+
+Note that you should be careful to make sure ````on_exception```` never raises an exception itself.
+If it does, this second exception will be ignored.
+Thus it is best to limit the use of ````on_exception```` to logging exceptions in a common base class.
+
+## Blocking code
+
+Occassionally you will have a need to execute blocking code in one of your actors.
+The most common cases of blocking code are network IO, disk IO, database queries, and the ````sleep```` function.
+
+Actors have a convenient method named ````blocking!```` that you should use to wrap such code.
+Under the hood this method is expanding and contracting the thread pool to compensate for the blocked thread.
+This will prevent thread pool starvation.
+
+The ````blocking!```` method is designed to work with dedicated and non-dedicated actors.
+By using this method in all of your actors, you will make it easy to convert between the two types.
+
+An actor's ````wait!```` method (used with futures) already calls ````blocking!```` for you.
+
+If for some reason Ruby can't create a new thread, Ruby will raise a ````ThreadError```` and your actor will die.
+Most modern operating systems can support many thousands of simultanous threads so refer to your operating system documentation as you may need to increase the limits.
+
+To support in the tens of thousands, hundreds of thousands, or potentially millions of actors, you will need to use non-blocking actors.
+
+    class MyActor < Tribe::Actor
+    private
+      def on_start(event)
+        blocking! do
+          sleep 6
         end
       end
+
     end
 
-    # 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
+    # Print the default pool size.
+    puts "Pool size (before): #{Workers.pool.size}"
+
+    # Spawn some actors that go to sleep for a bit.
+    100.times do
+      actor = Tribe.root.spawn!(MyActor)
+      actor.direct_message!(:start)
     end
 
-    # Create the top-level actor.
-    top = Tribe.root.spawn(Level1, :name => 'root')
+    # Wait for all of the actors to sleep.
+    sleep(2)
+
+    # The pool size is increased by 100 threads.
+    puts "Pool size (during): #{Workers.pool.size}"
 
-    # Tell the top-level actor to create the tree of children.
-    top.deliver_message!(:spawn)
+    # Wait for all of the actors to stop sleeping.
+    sleep(10)
+
+    # The pool size is back to the default size.
+    puts "Pool size (after): #{Workers.pool.size}"
+
+## Debugging
 
-#### Important!
+Tribe is written in pure Ruby so it will work with all existing debuggers that support Ruby & threads.
+[Byebug] (https://github.com/deivid-rodriguez/byebug) is commonly used with MRI Ruby 2.X and will let you set breakpoints.
 
-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.
+The most common problem you will encounter with actors is that they die due to exceptions.
+You can access the exception that caused an actor to die by calling the ````exception```` method on the actor:
+
+    actor = Tribe::Actor.new
+    actor.perform! { raise 'goodbye' }
+    sleep(3)
+    e = actor.exception
+    puts "#{e.class.name}: #{e.message}:\n#{e.backtrace.join("\n")}"
 
 ## Benchmarks
 
-  Please see the [performance] (https://github.com/chadrem/tribe/wiki/Performance "performance") wiki page for more information.
+Please see the [performance] (https://github.com/chadrem/tribe/wiki/Performance "performance") wiki page for more information.
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Bug reports and pull requests are welcome on GitHub at https://github.com/chadrem/tribe.