concurrent-ruby 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: de0e0da91bc658bb4ed962ec88d82b3997b95a09
-  data.tar.gz: 35d3a5d3111ff16f3a7782f38736e84b25007fc1
+  metadata.gz: 755d47349aa9471448745d4d102eef30c9ff39f9
+  data.tar.gz: 3ed64a6aa698387b8043cceb72bb64c3b45d4f2f
 SHA512:
-  metadata.gz: 804490a05bcf41198363ec31ec285535039dd9beb9a4a46cf2e266c7b26ca333f9dada1ecfafacb8a3f9146c1b63cf5b699385d011306cceea8d6ddbc78f9ff8
-  data.tar.gz: b2a9eaec2ce45a071ee8ef9dc3695f3842c8b23dea252d52e8c3ac5a0fd533aa290ff6e278055173388459a92f0d33c8e41d896d872b04870a9575d5e1a2e4c3
+  metadata.gz: ba402eee86f4836735c7f659ac45c0c8df22863d718435179348a4fa5707a1671629d113c615ea4f87a0ac60019999556c1ae84b468c8abca3907e7e7efb6ea1
+  data.tar.gz: a689c273e9173afffa0945b4621b88bd9276cf478c4aaf9692bddb78ed610521c9a22fb449ca229feb869654018f37df670f19eb172e027ba4a631f5482692ec

data/README.md

@@ -1,86 +1,42 @@
 # Concurrent Ruby [![Build Status](https://secure.travis-ci.org/jdantonio/concurrent-ruby.png)](https://travis-ci.org/jdantonio/concurrent-ruby?branch=master) [![Coverage Status](https://coveralls.io/repos/jdantonio/concurrent-ruby/badge.png)](https://coveralls.io/r/jdantonio/concurrent-ruby) [![Dependency Status](https://gemnasium.com/jdantonio/concurrent-ruby.png)](https://gemnasium.com/jdantonio/concurrent-ruby)
 
-Modern concurrency tools including agents, futures, promises, thread pools, supervisors, and more.
-Inspired by Erlang, Clojure, Scala, Go, Java, JavaScript, and classic concurrency patterns.
-
-## Introduction
-
-The old-school "lock and synchronize" approach to concurrency is dead. The
-future of concurrency is asynchronous. Send out a bunch of independent
-[actors](http://en.wikipedia.org/wiki/Actor_model) to do your bidding and
-process the results when you are ready. Many modern programming languages (like
+Modern concurrency tools for Ruby. Inspired by
 [Erlang](http://www.erlang.org/doc/reference_manual/processes.html),
 [Clojure](http://clojure.org/concurrent_programming),
 [Scala](http://www.scala-lang.org/api/current/index.html#scala.actors.Actor),
 [Haskell](http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell),
 [F#](http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx),
 [C#](http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx),
-[Java](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html)...)
-provide asynchronous concurrency mechanisms within their standard libraries, the
-runtime environment, or the language iteself. This library implements a few of
-the most interesting and useful of those variations.
-
-Remember, *there is no silver bullet in concurrent programming.* Concurrency is hard.
-These tools will help ease the burden, but at the end of the day it is essential that you
-*know what you are doing.*
-
-* Decouple business logic from concurrency logic
-* Test business logic separate from concurrency logic
-* Keep the intersection of business logic and concurrency and small as possible
-* Don't share mutable data unless absolutely necessary
-* Protect shared data as much as possible (prefer [immutability](https://github.com/harukizaemon/hamster))
-* Don't mix Ruby's [concurrency](http://ruby-doc.org/core-2.0.0/Thread.html)
-  [primitives](http://www.ruby-doc.org/core-2.0.0/Mutex.html) with asynchronous concurrency libraries
-
-The project is hosted on the following sites:
+[Java](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html),
+and classic concurrency patterns.
 
-* [RubyGems project page](https://rubygems.org/gems/concurrent-ruby)
-* [Source code on GitHub](https://github.com/jdantonio/concurrent-ruby)
-* [YARD documentation on RubyDoc.info](http://rubydoc.info/github/jdantonio/concurrent-ruby/frames)
-* [Continuous integration on Travis-CI](https://travis-ci.org/jdantonio/concurrent-ruby)
-* [Dependency tracking on Gemnasium](https://gemnasium.com/jdantonio/concurrent-ruby)
-* [Follow me on Twitter](https://twitter.com/jerrydantonio)
-
-### Conference Presentations
-
-I've given several conference presentations on concurrent programming with this gem.
-Check them out:
-
-* ["Advanced Concurrent Programming in Ruby"](http://rubyconf.org/program#jerry-dantonio)
-  at [RubyConf 2013](http://rubyconf.org/) used [this](https://github.com/jdantonio/concurrent-ruby-presentation) version of the presentation
-* ["Advanced Multithreading in Ruby"](http://cascadiaruby.com/#advanced-multithreading-in-ruby)
-  at [Cascadia Ruby 2013](http://cascadiaruby.com/) used [this](https://github.com/jdantonio/concurrent-ruby-presentation/tree/cascadia-ruby-2013) version of the presentation
-* I'll be giving ["Advanced Concurrent Programming in Ruby"](http://codemash.org/sessions)
-  at [CodeMash 2014](http://codemash.org/)
-
-## Goals
+The design goals of this gem are:
 
 * Stay true to the spirit of the languages providing inspiration
 * But implement in a way that makes sense for Ruby
 * Keep the semantics as idiomatic Ruby as possible
 * Support features that make sense in Ruby
 * Exclude features that don't make sense in Ruby
-* Keep everything small
-* Be as fast as reasonably possible
+* Be small, lean, and loosely coupled
 
-## Features (and Documentation)
+## Features & Documentation
 
-Several features from Erlang, Go, Clojure, Java, and JavaScript have been implemented thus far:
-
-* Clojure inspired [Agent](https://github.com/jdantonio/concurrent-ruby/blob/master/md/agent.md)
-* Clojure inspired [Future](https://github.com/jdantonio/concurrent-ruby/blob/master/md/future.md)
-* Scala inspired [Actor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/actor.md)
-* Go inspired [Goroutine](https://github.com/jdantonio/concurrent-ruby/blob/master/md/goroutine.md)
-* JavaScript inspired [Promise](https://github.com/jdantonio/concurrent-ruby/blob/master/md/promise.md)
-* Java inspired [Thread Pools](https://github.com/jdantonio/concurrent-ruby/blob/master/md/thread_pool.md)
+* Clojure-inspired [Agent](https://github.com/jdantonio/concurrent-ruby/blob/master/md/agent.md)
+* Clojure-inspired [Future](https://github.com/jdantonio/concurrent-ruby/blob/master/md/future.md)
+* Scala-inspired [Actor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/actor.md)
+* JavaScript-inspired [Promise](https://github.com/jdantonio/concurrent-ruby/blob/master/md/promise.md)
+* Java-inspired [Thread Pools](https://github.com/jdantonio/concurrent-ruby/blob/master/md/thread_pool.md)
 * Old school [events](http://msdn.microsoft.com/en-us/library/windows/desktop/ms682655.aspx) from back in my Visual C++ days
-* Repeated task execution with Java inspired [TimerTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/timer_task.md) service
-* Scheduled task execution with Java inspired [ScheduledTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/scheduled_task.md) service
-* Erlang inspired [Supervisor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/supervisor.md) for managing long-running threads
+* Repeated task execution with Java-inspired [TimerTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/timer_task.md) service
+* Scheduled task execution with Java-inspired [ScheduledTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/scheduled_task.md) service
+* Erlang-inspired [Supervisor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/supervisor.md) for managing long-running threads
+* Actor variant [Channel](https://github.com/jdantonio/concurrent-ruby/blob/master/md/channel.md)
+  loosely based on the [MailboxProcessor](http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx)
+  agent in [F#](http://msdn.microsoft.com/en-us/library/ee370357.aspx)
 
-### Is it any good?
+### Semantic Versioning
 
-[Yes](http://news.ycombinator.com/item?id=3067434)
+*Beginning with v0.4.0 this gem will strictly adhere to the rules of semantic versioning.*
 
 ### Supported Ruby versions
 
@@ -89,188 +45,83 @@ It should be fully compatible with any Ruby interpreter that is 1.9.x compliant.
 about Rubinius or the others to fully support them. I can promise good karma and attribution on this page
 to anyone wishing to take responsibility for verifying compaitibility with any Ruby other than MRI.
 
-### Install
-
-```shell
-gem install concurrent-ruby
-```
-
-or add the following line to Gemfile:
-
-```ruby
-gem 'concurrent-ruby'
-```
-
-and run `bundle install` from your shell.
-
-Once you've installed the gem you must `require` it in your project:
-
-```ruby
-require 'concurrent'
-```
-
-### Examples
-
-For complete examples, see the specific documentation for each abstraction.
-The examples below are just basic usage.
-
-#### Goroutine (Go)
-
-Full documentation: [Goroutine](https://github.com/jdantonio/concurrent-ruby/blob/master/md/goroutine.md)
-
-```ruby
-require 'concurrent'
-
-go('foo'){|echo| sleep(0.1); print "#{echo}\n"; sleep(0.1); print "Boom!\n" }
-sleep(0.5)
-
-#=> foo
-#=> Boom!
-```
-
-#### Agent (Clojure)
-
-Full documentation: [Agent](https://github.com/jdantonio/concurrent-ruby/blob/master/md/agent.md)
-
-```ruby
-require 'concurrent'
-
-score = Concurrent::Agent.new(10)
-score.value #=> 10
-
-score << proc{|current| current + 100 }
-sleep(0.1)
-score.value #=> 110
-```
-
-#### Future (Clojure)
+### Example
 
-Full documentation: [Future](https://github.com/jdantonio/concurrent-ruby/blob/master/md/future.md)
+Many more code examples can be found in the documentation for each class (linked above).
+This one simple example shows some of the power of this gem.
 
 ```ruby
 require 'concurrent'
+require 'faker'
 
-count = Concurrent::Future.new{ sleep(1); 10 }
-count.state #=> :pending
-# do stuff...
-count.value #=> 10 (after blocking)
-```
-
-#### Promise (JavaScript)
-
-Full documentation: [Promise](https://github.com/jdantonio/concurrent-ruby/blob/master/md/promise.md)
-
-```ruby
-require 'concurrent'
-
-p = Concurrent::Promise.new("Jerry", "D'Antonio"){|a, b| "#{a} #{b}" }.
-    then{|result| "Hello #{result}." }.
-    rescue(StandardError){|ex| puts "Boom!" }.
-    then{|result| "#{result} Would you like to play a game?"}
-sleep(1)
-p.value #=> "Hello Jerry D'Antonio. Would you like to play a game?" 
-```
-
-#### Thread Pools (Java)
-
-Full documentation: [Thread Pools](https://github.com/jdantonio/concurrent-ruby/blob/master/md/thread_pool.md)
-
-```ruby
-require 'concurrent'
-
-pool = Concurrent::FixedThreadPool.new(2)
-pool.size #=> 2
-
-pool.post{ sleep(0.5); print "Boom!\n" }
-pool.size #=> 2
-
-sleep(1)
-#=> Boom!
-
-pool = Concurrent::CachedThreadPool.new
-pool.size #=> 0
-
-pool << proc{ sleep(0.5); print "Boom!\n" }
-pool.size #=> 1
-
-sleep(1)
-#=> Boom!
-```
-
-#### TimerTask (Java)
-
-Full documentation: [TimerTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/timer_task.md)
-
-```ruby
-require 'concurrent'
-
-ec = Concurrent::TimerTask.run{ puts 'Boom!' }
-
-ec.execution_interval #=> 60 == Concurrent::TimerTask::EXECUTION_INTERVAL
-ec.timeout_interval   #=> 30 == Concurrent::TimerTask::TIMEOUT_INTERVAL
-ec.status             #=> "sleep"
-
-# wait 60 seconds...
-#=> 'Boom!'
-
-ec.kill #=> true
-```
+class EchoActor < Concurrent::Actor
+  def act(*message)
+    puts "#{message} handled by #{self}"
+  end
+end
 
-#### ScheduledTask (Java)
+mailbox, pool = EchoActor.pool(5)
 
-Full documentation: [ScheduledTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/scheduled_task.md)
+timer_proc = proc do
+  mailbox.post(Faker::Company.bs)
+end
 
-*TBD*
+t1 = Concurrent::TimerTask.new(execution_interval: rand(5)+1, &timer_proc)
+t2 = Concurrent::TimerTask.new(execution_interval: rand(5)+1, &timer_proc)
 
-#### Actor (Scala)
+overlord = Concurrent::Supervisor.new
 
-Full documentation: [Actor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/actor.md)
+overlord.add_worker(t1)
+overlord.add_worker(t2)
+pool.each{|actor| overlord.add_worker(actor)}
 
-```ruby
-class FinanceActor < Concurrent::Actor
-  def act(query)
-    finance = Finance.new(query)
-    print "[#{Time.now}] RECEIVED '#{query}' to #{self} returned #{finance.update.suggested_symbols}\n\n"
-  end
-end
+overlord.run!
 
-financial, pool = FinanceActor.pool(5)
+#=> ["mesh proactive platforms"] handled by #<EchoActor:0x007fa5ac18bdf8>
+#=> ["maximize sticky portals"] handled by #<EchoActor:0x007fa5ac18bdd0>
+#=> ["morph bleeding-edge markets"] handled by #<EchoActor:0x007fa5ac18bd80>
+#=> ["engage clicks-and-mortar interfaces"] handled by #<EchoActor:0x007fa5ac18bd58>
+#=> ["monetize transparent infrastructures"] handled by #<EchoActor:0x007fa5ac18bd30>
+#=> ["morph sexy e-tailers"] handled by #<EchoActor:0x007fa5ac18bdf8>
+#=> ["exploit dot-com models"] handled by #<EchoActor:0x007fa5ac18bdd0>
+#=> ["incentivize virtual deliverables"] handled by #<EchoActor:0x007fa5ac18bd80>
+#=> ["enhance B2B models"] handled by #<EchoActor:0x007fa5ac18bd58>
+#=> ["envisioneer real-time architectures"] handled by #<EchoActor:0x007fa5ac18bd30>
 
-pool << 'YAHOO'
-pool << 'Micosoft'
-pool << 'google'
+overlord.stop
 ```
 
-#### Supervisor (Erlang)
-
-Full documentation: [Supervisor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/supervisor.md)
+### Disclaimer
 
-```ruby
-pong = Pong.new
-ping = Ping.new(10000, pong)
-pong.ping = ping
-
-task = Concurrent::TimerTask.new{ print "Boom!\n" }
-
-boss = Concurrent::Supervisor.new
-boss.add_worker(ping)
-boss.add_worker(pong)
-boss.add_worker(task)
+Remember, *there is no silver bullet in concurrent programming.* Concurrency is hard.
+These tools will help ease the burden, but at the end of the day it is essential that you
+*know what you are doing.*
 
-boss.run!
+* Decouple business logic from concurrency logic
+* Test business logic separate from concurrency logic
+* Keep the intersection of business logic and concurrency and small as possible
+* Don't share mutable data unless absolutely necessary
+* Protect shared data as much as possible (prefer [immutability](https://github.com/harukizaemon/hamster))
+* Don't mix Ruby's [concurrency](http://ruby-doc.org/core-2.0.0/Thread.html)
+  [primitives](http://www.ruby-doc.org/core-2.0.0/Mutex.html) with asynchronous concurrency libraries
 
-ping << :pong
-```
+### Conference Presentations
 
-## Todo
+I've given several conference presentations on concurrent programming with this gem.
+Check them out:
 
-* [Task Parallel Library (TPL)](http://msdn.microsoft.com/en-us/library/dd460717.aspx)
-  * [Data Parallelism](http://msdn.microsoft.com/en-us/library/dd537608.aspx)
-  * [Task Parallelism](http://msdn.microsoft.com/en-us/library/dd537609.aspx)
-* More Erlang goodness
-  * [gen_server](http://www.erlang.org/doc/man/gen_server.html)
-  * [gen_event](http://www.erlang.org/doc/man/gen_event.html)
-  * [gen_fsm](http://www.erlang.org/doc/man/gen_fsm.html)
+* ["Advanced Concurrent Programming in Ruby"](http://rubyconf.org/program#jerry-dantonio)
+  at [RubyConf 2013](http://rubyconf.org/)
+  used [this](https://github.com/jdantonio/concurrent-ruby-presentation) version of the presentation
+  and is available for viewing on [Confreaks](http://www.confreaks.com/videos/2872-rubyconf2013-advanced-concurrent-programming-in-ruby)
+* ["Advanced Multithreading in Ruby"](http://cascadiaruby.com/#advanced-multithreading-in-ruby)
+  at [Cascadia Ruby 2013](http://cascadiaruby.com/)
+  used [this](https://github.com/jdantonio/concurrent-ruby-presentation/tree/cascadia-ruby-2013) version of the presentation
+  and is available for viewing on [Confreaks](http://www.confreaks.com/videos/2790-cascadiaruby2013-advanced-multithreading-in-ruby)
+* [Cleveland Ruby Brigade](http://www.meetup.com/ClevelandRuby/events/149981942/) meetup in December of 2013
+  used [this](https://github.com/jdantonio/concurrent-ruby-presentation/releases/tag/clerb-dec-2013) version of the presentation
+* I'll be giving ["Advanced Concurrent Programming in Ruby"](http://codemash.org/sessions)
+  at [CodeMash 2014](http://codemash.org/)
 
 ## Contributing
 

data/lib/concurrent.rb

@@ -1,17 +1,18 @@
 require 'concurrent/version'
 
-
 require 'concurrent/actor'
 require 'concurrent/agent'
 require 'concurrent/contract'
+require 'concurrent/channel'
 require 'concurrent/dereferenceable'
 require 'concurrent/event'
 require 'concurrent/future'
-require 'concurrent/goroutine'
 require 'concurrent/obligation'
+require 'concurrent/postable'
 require 'concurrent/promise'
 require 'concurrent/runnable'
 require 'concurrent/scheduled_task'
+require 'concurrent/stoppable'
 require 'concurrent/supervisor'
 require 'concurrent/timer_task'
 require 'concurrent/utilities'
@@ -22,3 +23,18 @@ require 'concurrent/cached_thread_pool'
 require 'concurrent/fixed_thread_pool'
 
 require 'concurrent/event_machine_defer_proxy' if defined?(EventMachine)
+
+# Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
+# F#, C#, Java, and classic concurrency patterns.
+# 
+# The design goals of this gem are:
+# 
+# * Stay true to the spirit of the languages providing inspiration
+# * But implement in a way that makes sense for Ruby
+# * Keep the semantics as idiomatic Ruby as possible
+# * Support features that make sense in Ruby
+# * Exclude features that don't make sense in Ruby
+# * Be small, lean, and loosely coupled
+module Concurrent
+
+end

data/lib/concurrent/actor.rb

@@ -3,78 +3,132 @@ require 'observer'
 
 require 'concurrent/event'
 require 'concurrent/obligation'
+require 'concurrent/postable'
 require 'concurrent/runnable'
 
 module Concurrent
 
-  module Postable
-
-    Package = Struct.new(:message, :handler, :notifier)
-
-    def post(*message)
-      return false unless ready?
-      queue.push(Package.new(message))
-      return queue.length
-    end
-
-    def <<(message)
-      post(*message)
-      return self
-    end
-
-    def post?(*message)
-      return nil unless ready?
-      contract = Contract.new
-      queue.push(Package.new(message, contract))
-      return contract
-    end
-
-    def post!(seconds, *message)
-      raise Concurrent::Runnable::LifecycleError unless ready?
-      raise Concurrent::TimeoutError if seconds.to_f <= 0.0
-      event = Event.new
-      cback = Queue.new
-      queue.push(Package.new(message, cback, event))
-      if event.wait(seconds)
-        result = cback.pop
-        if result.is_a?(Exception)
-          raise result
-        else
-          return result
-        end
-      else
-        event.set # attempt to cancel
-        raise Concurrent::TimeoutError
-      end
-    end
-
-    def forward(receiver, *message)
-      return false unless ready?
-      queue.push(Package.new(message, receiver))
-      return queue.length
-    end
-
-    def ready?
-      if self.respond_to?(:running?) && ! running?
-        return false
-      else
-        return true
-      end
-    end
-
-    private
-
-    def queue
-      @queue ||= Queue.new
-    end
-  end
-
+  # Actor-based concurrency is all the rage in some circles. Originally described in
+  # 1973, the actor model is a paradigm for creating asynchronous, concurrent objects
+  # that is becoming increasingly popular. Much has changed since actors were first
+  # written about four decades ago, which has led to a serious fragmentation within
+  # the actor community. There is *no* universally accepted, strict definition of
+  # "actor" and actor implementations differ widely between languages and libraries.
+  # 
+  # A good definition of "actor" is:
+  # 
+  #   An independent, concurrent, single-purpose, computational entity that communicates exclusively via message passing.
+  # 
+  # The `Concurrent::Actor` class in this library is based solely on the
+  # {http://www.scala-lang.org/api/current/index.html#scala.actors.Actor Actor} trait
+  # defined in the Scala standard library. It does not implement all the features of
+  # Scala's `Actor` but its behavior for what *has* been implemented is nearly identical.
+  # The excluded features mostly deal with Scala's message semantics, strong typing,
+  # and other characteristics of Scala that don't really apply to Ruby.
+  # 
+  # Unlike most of the abstractions in this library, `Actor` takes an *object-oriented*
+  # approach to asynchronous concurrency, rather than a *functional programming*
+  # approach.
+  #   
+  # Because `Actor` mixes in the `Concurrent::Runnable` module subclasses have access to
+  # the `#on_error` method and can override it to implement custom error handling. The
+  # `Actor` base class does not use `#on_error` so as to avoid conflit with subclasses
+  # which override it. Generally speaking, `#on_error` should not be used. The `Actor`
+  # base class provides concictent, reliable, and robust error handling already, and
+  # error handling specifics are tied to the message posting method. Incorrect behavior
+  # in an `#on_error` override can lead to inconsistent `Actor` behavior that may lead
+  # to confusion and difficult debugging.
+  #   
+  # The `Actor` superclass mixes in the Ruby standard library
+  # {http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html Observable}
+  # module to provide consistent callbacks upon message processing completion. The normal
+  # `Observable` methods, including `#add_observer` behave normally. Once an observer
+  # is added to an `Actor` it will be notified of all messages processed *after*
+  # addition. Notification will *not* occur for any messages that have already been
+  # processed.
+  #   
+  # Observers will be notified regardless of whether the message processing is successful
+  # or not. The `#update` method of the observer will receive four arguments. The
+  # appropriate method signature is:
+  #   
+  #   def update(time, message, result, reason)
+  #   
+  # These four arguments represent:
+  #   
+  # * The time that message processing was completed
+  # * An array containing all elements of the original message, in order
+  # * The result of the call to `#act` (will be `nil` if an exception was raised)
+  # * Any exception raised by `#act` (or `nil` if message processing was successful)
+  #
+  # @example Actor Ping Pong
+  #   class Ping < Concurrent::Actor
+  #   
+  #     def initialize(count, pong)
+  #       super()
+  #       @pong = pong
+  #       @remaining = count
+  #     end
+  #     
+  #     def act(msg)
+  #   
+  #       if msg == :pong
+  #         print "Ping: pong\n" if @remaining % 1000 == 0
+  #         @pong.post(:ping)
+  #   
+  #         if @remaining > 0
+  #           @pong << :ping
+  #           @remaining -= 1
+  #         else
+  #           print "Ping :stop\n"
+  #           @pong << :stop
+  #           self.stop
+  #         end
+  #       end
+  #     end
+  #   end
+  #   
+  #   class Pong < Concurrent::Actor
+  #   
+  #     attr_writer :ping
+  #   
+  #     def initialize
+  #       super()
+  #       @count = 0
+  #     end
+  #   
+  #     def act(msg)
+  #   
+  #       if msg == :ping
+  #         print "Pong: ping\n" if @count % 1000 == 0
+  #         @ping << :pong
+  #         @count += 1
+  #   
+  #       elsif msg == :stop
+  #         print "Pong :stop\n"
+  #         self.stop
+  #       end
+  #     end
+  #   end
+  #   
+  #   pong = Pong.new
+  #   ping = Ping.new(10000, pong)
+  #   pong.ping = ping
+  #   
+  #   t1 = ping.run!
+  #   t2 = pong.run!
+  #   
+  #   ping << :pong
+  #
+  # @see http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
   class Actor
     include Observable
-    include Runnable
     include Postable
+    include Runnable
+
+    private
 
-    class Poolbox
+    # @!visibility private
+    class Poolbox # :nodoc:
       include Postable
 
       def initialize(queue)
@@ -82,12 +136,53 @@ module Concurrent
       end
     end
 
-    # FIXME: duplicate the block (thread safety)
-    def self.pool(count, &block)
+    public
+
+    # Create a pool of actors that share a common mailbox.
+    #   
+    # Every `Actor` instance operates on its own thread. When one thread isn't enough capacity
+    # to manage all the messages being sent to an `Actor` a *pool* can be used instead. A pool
+    # is a collection of `Actor` instances, all of the same type, that shate a message queue.
+    # Messages from other threads are all sent to a single queue against which all `Actor`s
+    # load balance.
+    #
+    # @param [Integer] count the number of actors in the pool
+    # @param [Array] args zero or more arguments to pass to each actor in the pool
+    #
+    # @return [Array] two-element array with the shared mailbox as the first element
+    #   and an array of actors as the second element
+    #
+    # @raise ArgumentError if `count` is zero or less
+    #
+    # @example
+    #   class EchoActor < Concurrent::Actor
+    #     def act(*message)
+    #       puts "#{message} handled by #{self}"
+    #     end
+    #   end
+    #     
+    #   mailbox, pool = EchoActor.pool(5)
+    #   pool.each{|echo| echo.run! }
+    #     
+    #   10.times{|i| mailbox.post(i) }
+    #   #=> [0] handled by #<EchoActor:0x007fc8014fb8b8>
+    #   #=> [1] handled by #<EchoActor:0x007fc8014fb890>
+    #   #=> [2] handled by #<EchoActor:0x007fc8014fb868>
+    #   #=> [3] handled by #<EchoActor:0x007fc8014fb890>
+    #   #=> [4] handled by #<EchoActor:0x007fc8014fb840>
+    #   #=> [5] handled by #<EchoActor:0x007fc8014fb8b8>
+    #   #=> [6] handled by #<EchoActor:0x007fc8014fb8b8>
+    #   #=> [7] handled by #<EchoActor:0x007fc8014fb818>
+    #   #=> [8] handled by #<EchoActor:0x007fc8014fb890>
+    def self.pool(count, *args, &block)
       raise ArgumentError.new('count must be greater than zero') unless count > 0
       mailbox = Queue.new
       actors = count.times.collect do
-        actor = self.new(&block)
+        if block_given?
+          actor = self.new(*args, &block.dup)
+        else
+          actor = self.new(*args)
+        end
         actor.instance_variable_set(:@queue, mailbox)
         actor
       end
@@ -96,7 +191,20 @@ module Concurrent
 
     protected
 
-    def act(*args)
+    # Actors are defined by subclassing the `Concurrent::Actor` class and overriding the
+    # #act method. The #act method can have any signature/arity but `def act(*args)`
+    # is the most flexible and least error-prone signature. The #act method is called in
+    # response to a message being post to the `Actor` instance (see *Behavior* below).
+    #
+    # @param [Array] message one or more arguments representing the message sent to the
+    #   actor via one of the Concurrent::Postable methods
+    #
+    # @return [Object] the result obtained when the message is successfully processed
+    #
+    # @raise NotImplementedError unless overridden in the `Actor` subclass
+    # 
+    # @!visibility public
+    def act(*message)
       raise NotImplementedError.new("#{self.class} does not implement #act")
     end
 
@@ -124,12 +232,12 @@ module Concurrent
       rescue => ex
         on_error(Time.now, package.message, ex)
       ensure
-        if package.handler.is_a?(Contract)
-          package.handler.complete(result, ex)
-        elsif notifier.is_a?(Event) && ! notifier.set?
+        if notifier.is_a?(Event) && ! notifier.set?
           package.handler.push(result || ex)
           package.notifier.set
-        elsif package.handler.is_a?(Actor) && ex.nil?
+        elsif package.handler.is_a?(Contract)
+          package.handler.complete(result, ex)
+        elsif package.handler.respond_to?(:post) && ex.nil?
           package.handler.post(result)
         end