tribe 0.2.1 → 0.2.2

data/README.md

@@ -25,6 +25,15 @@ Or install it yourself as:
 
 ## Actors
 
+Actors are light-weight objects which 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.
+The return value will always be nil since messaging is asynchronous.
+
     # Create your custom actor class.
     class MyActor < Tribe::Actor
       private
@@ -52,7 +61,7 @@ Or install it yourself as:
       MyActor.new(:name => "my_actor_#{i}")
     end
 
-    # Send an event to each actors.  Find each actor using the global registry.
+    # Send an event to each actor.
     100.times do |i|
       actor = Tribe.registry["my_actor_#{i}"]
       actor.enqueue(:my_custom, 'hello world')
@@ -64,11 +73,11 @@ Or install it yourself as:
       actor.enqueue(:shutdown)
     end
 
-#### Implementation notes
-*Important*: Because actors use a shared thread pool, it is important that they don't block for long periods of time (short periods are fine).
+#### 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):
+#### Options (defaults below)
 
     actor = Tribe::Actor.new(
       :logger => nil,                   # Ruby logger instance.
@@ -79,9 +88,6 @@ Actors that block for long periods of time should use a dedicated thread (:dedic
       :name => nil                      # The name of the actor (must be unique in the registry).
     )
 
-    The DedicatedActor class is a simple wrapper around the Actor class.
-    It takes all the same options except for :pool and :dedicated since they aren't applicable.
-
 ## Registries
 
 Registries hold references to named actors so that you can easily find them.
@@ -130,15 +136,22 @@ Both one-shot and periodic timers are provided.
       actor.enqueue(:shutdown)
     end
 
-## Futures (experimental)
+## Futures
 
-Futures allow an actor to ask another actor to perform a computation and then return the result.
-Tribe includes both blocking and non-blocking actors.
-You should prefer to use non-blocking actors in your code when possible due to performance reasons (see details below).
+As mentioned above, message passing with the "enqueue" 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.
 
 #### Non-blocking
 
-Non-blocking actors are asynchronous and use callbacks.
+Non-blocking futures are asynchronous and use callbacks.
 No waiting for a result is involved.
 The actor will continue to process other events.
 
@@ -194,11 +207,11 @@ The actor will continue to process other events.
 
 *Important*: You must use Actor#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 race conditions and other nasty things.
+Failure to do so will result in many nasty things.
 
 #### Blocking
 
-Blocking actors are synchronous.
+Blocking futures are synchronous.
 The actor won't process any other events until the future has a result.
 
     class ActorA < Tribe::Actor
@@ -249,13 +262,16 @@ The actor won't process any other events until the future has a result.
 
 #### Futures and Performance
 
-You should prefer non-blocking futures as much as possible in your application code.
-This is because a blocking future (Future#wait) causes the current actor (and thread) to sleep.
+Futures have overhead associated with them.
+You should avoid them unless you are actaully interested in the result.
+
+You should also prefer non-blocking futures over blocking ones.
+This is because a blocking future causes the current actor (and thread) to sleep.
 
 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.
 
-If you choose to use blocing futures then it is highly recommended that you only use them with dedicated actors.
+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.
 
@@ -263,6 +279,8 @@ The downside to using dedicated actors is that they consume more resources and y
 
 - Supervisors.
 - Linking.
+- Future timeouts.
+- Clustering.
 
 ## Contributing
 

data/lib/tribe/version.rb

@@ -1,3 +1,3 @@
 module Tribe
-  VERSION = '0.2.1'
+  VERSION = '0.2.2'
 end

data/tribe.gemspec

@@ -15,5 +15,5 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Tribe::VERSION
 
-  gem.add_dependency('workers', '0.1.2')
+  gem.add_dependency('workers', '0.1.4')
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tribe
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-27 00:00:00.000000000 Z
+date: 2013-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: workers
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.4
 description: Tribe is a Ruby gem that implements event-driven actors.
 email:
 - chad@remesch.com