concurrent-ruby 0.6.0 → 0.7.0.rc0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58bf31b4139ff60bd206c0771a4616653c77d710
-  data.tar.gz: 1fbbe6556817458272475deac127e92fc0c723a2
+  metadata.gz: a37030c113bbaf5da04499b31efd48b49c8244e6
+  data.tar.gz: 794a39695eadb43c80668f28f8c9eb367fbd8dc3
 SHA512:
-  metadata.gz: 4d701a724fe2bb49c0bfa6c8cd3ccb242af88983ac04d90ac622a40a00e3e8e39b21a635a090c6dd808124f82733c66b99fabf05504691dcbe5a4a1f97ab8f33
-  data.tar.gz: 6bc189a09d26d754131c4ca8f09ec45912f2c0a4bb22ef3a578daa5781103df38597c8ab86573a78f211aa88f1f635188673b3d0d51334f56588b5c3d7c3f841
+  metadata.gz: c99611c6311e743524a1769f6c1a663be7cee748813d772c5a5b5e7f9bdcd344c58d696e7d74dcae1c7e285fb7caa2d3e0cef0150a125e546e12474d9d1a3184
+  data.tar.gz: 3678784b9161c7b0f59ff608950fc2eb17887281be9ffbb842f4bde178303b0ab347d2e1b82111fd43604d4a4419354277524abe55c20222370464ad5735c85b

data/README.md

@@ -1,79 +1,82 @@
 # Concurrent Ruby
-[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.png)](http://badge.fury.io/rb/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) [![Code Climate](https://codeclimate.com/github/jdantonio/concurrent-ruby.png)](https://codeclimate.com/github/jdantonio/concurrent-ruby) [![Inline docs](http://inch-pages.github.io/github/jdantonio/concurrent-ruby.png)](http://inch-pages.github.io/github/jdantonio/concurrent-ruby) [![Dependency Status](https://gemnasium.com/jdantonio/concurrent-ruby.png)](https://gemnasium.com/jdantonio/concurrent-ruby)
+[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.png)](http://badge.fury.io/rb/concurrent-ruby) [![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby) [![Coverage Status](https://coveralls.io/repos/ruby-concurrency/concurrent-ruby/badge.png)](https://coveralls.io/r/ruby-concurrency/concurrent-ruby) [![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.png)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby) [![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.png)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby) [![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.png)](https://gemnasium.com/ruby-concurrency/concurrent-ruby)
 
 <table>
-<tr>
-<td align="left" valign="top">
-<p>
-Modern concurrency tools for Ruby. Inspired by
-<a href="http://www.erlang.org/doc/reference_manual/processes.html">Erlang</a>,
-<a href="http://clojure.org/concurrent_programming">Clojure</a>,
-<a href="http://www.scala-lang.org/api/current/index.html#scala.actors.Actor">Scala</a>,
-<a href="http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell">Haskell</a>,
-<a href="http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx">F#</a>,
-<a href="http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx">C#</a>,
-<a href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html">Java</a>,
-and classic concurrency patterns.
-</p>
-<p>
-The design goals of this gem are:
-<ul>
-<li>Be an 'unopinionted' toolbox that provides useful utilities without debating which is better or why</li>
-<li>Remain free of external gem dependencies</li>
-<li>Stay true to the spirit of the languages providing inspiration</li>
-<li>But implement in a way that makes sense for Ruby</li>
-<li>Keep the semantics as idiomatic Ruby as possible</li>
-<li>Support features that make sense in Ruby</li>
-<li>Exclude features that don't make sense in Ruby</li>
-<li>Be small, lean, and loosely coupled</li>
-</ul>
-</p>
-</td>
-<td align="right" valign="top">
-<img src="https://raw.githubusercontent.com/wiki/jdantonio/concurrent-ruby/logo/concurrent-ruby-logo-300x300.png"/>
-</td>
-</tr>
+  <tr>
+    <td align="left" valign="top">
+      <p>
+        Modern concurrency tools for Ruby. Inspired by
+        <a href="http://www.erlang.org/doc/reference_manual/processes.html">Erlang</a>,
+        <a href="http://clojure.org/concurrent_programming">Clojure</a>,
+        <a href="http://akka.io/">Scala</a>,
+        <a href="http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell">Haskell</a>,
+        <a href="http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx">F#</a>,
+        <a href="http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx">C#</a>,
+        <a href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html">Java</a>,
+        and classic concurrency patterns.
+      </p>
+      <p>
+        The design goals of this gem are:
+        <ul>
+          <li>Be an 'unopinionated' toolbox that provides useful utilities without debating which is better or why</li>
+          <li>Remain free of external gem dependencies</li>
+          <li>Stay true to the spirit of the languages providing inspiration</li>
+          <li>But implement in a way that makes sense for Ruby</li>
+          <li>Keep the semantics as idiomatic Ruby as possible</li>
+          <li>Support features that make sense in Ruby</li>
+          <li>Exclude features that don't make sense in Ruby</li>
+          <li>Be small, lean, and loosely coupled</li>
+        </ul>
+      </p>
+    </td>
+    <td align="right" valign="top">
+      <img src="https://raw.githubusercontent.com/wiki/ruby-concurrency/concurrent-ruby/logo/concurrent-ruby-logo-300x300.png"/>
+    </td>
+  </tr>
 </table>
 
-### Install
+## Install
 
 ```shell
 gem install concurrent-ruby
 ```
+
 or add the following line to Gemfile:
 
 ```ruby
 gem 'concurrent-ruby'
 ```
+
 and run `bundle install` from your shell.
 
-*NOTE: There is an old gem from 2007 called "concurrent" that does not appear to be under active development. That isn't us. Please do not run* `gem install concurrent`*. It is not the droid you are looking for.*
+_NOTE: There is an old gem from 2007 called "concurrent" that does not appear to be under active development. That isn't us. Please do not run* `gem install concurrent`*. It is not the droid you are looking for._
 
 ## Features & Documentation
 
-Please see the [Concurrent Ruby Wiki](https://github.com/jdantonio/concurrent-ruby/wiki)
-or the [API documentation](http://rubydoc.info/github/jdantonio/concurrent-ruby/master/frames)
+Please see the [Concurrent Ruby Wiki](https://github.com/ruby-concurrency/concurrent-ruby/wiki)
+or the [API documentation](http://ruby-concurrency.github.io/concurrent-ruby/frames.html))
 for more information or join our [mailing list](http://groups.google.com/group/concurrent-ruby).
 
 There are many concurrency abstractions in this library. These abstractions can be broadly categorized
 into several general groups:
 
 * Asynchronous concurrency abstractions including
-  [Async](https://github.com/jdantonio/concurrent-ruby/wiki/Async),
-  [Agent](https://github.com/jdantonio/concurrent-ruby/wiki/Agent),
-  [Future](https://github.com/jdantonio/concurrent-ruby/wiki/Future),
-  [Promise](https://github.com/jdantonio/concurrent-ruby/wiki/Promise),
-  [ScheduledTask](https://github.com/jdantonio/concurrent-ruby/wiki/ScheduledTask),
-  and [TimerTask](https://github.com/jdantonio/concurrent-ruby/wiki/TimerTask) 
-* Erlang-inspired [Supervisor](https://github.com/jdantonio/concurrent-ruby/wiki/Supervisor) and other lifecycle classes/mixins
+  [Async](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Async),
+  [Agent](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Agent),
+  [Future](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Future),
+  [Promise](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Promise),
+  [ScheduledTask](https://github.com/ruby-concurrency/concurrent-ruby/wiki/ScheduledTask),
+  and [TimerTask](https://github.com/ruby-concurrency/concurrent-ruby/wiki/TimerTask) 
+* Erlang-inspired [Supervisor](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Supervisor) and other lifecycle classes/mixins
   for managing long-running threads
-* Thread-safe variables including [M-Structures](https://github.com/jdantonio/concurrent-ruby/wiki/MVar-(M-Structure)),
-  [I-Structures](https://github.com/jdantonio/concurrent-ruby/wiki/IVar-(I-Structure)),
-  [thread-local variables](https://github.com/jdantonio/concurrent-ruby/wiki/ThreadLocalVar),
-  atomic counters, and [software transactional memory](https://github.com/jdantonio/concurrent-ruby/wiki/TVar-(STM))
-* Thread synchronization classes and algorithms including [dataflow](https://github.com/jdantonio/concurrent-ruby/wiki/Dataflow), 
+* Thread-safe variables including [M-Structures](https://github.com/ruby-concurrency/concurrent-ruby/wiki/MVar-(M-Structure)),
+  [I-Structures](https://github.com/ruby-concurrency/concurrent-ruby/wiki/IVar-(I-Structure)),
+  [thread-local variables](https://github.com/ruby-concurrency/concurrent-ruby/wiki/ThreadLocalVar),
+  atomic counters, and [software transactional memory](https://github.com/ruby-concurrency/concurrent-ruby/wiki/TVar-(STM))
+* Thread synchronization classes and algorithms including [dataflow](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Dataflow), 
   timeout, condition, countdown latch, dependency counter, and event
-* Java-inspired [thread pools](https://github.com/jdantonio/concurrent-ruby/wiki/Thread%20Pools)
+* Java-inspired [thread pools](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Thread%20Pools)
+* New fast light-weighted [Actor model](http://ruby-concurrency.github.io/concurrent-ruby/frames.html#!Concurrent/Actress.html) implementation. 
 * And many more...
 
 ### Semantic Versioning
@@ -91,7 +94,7 @@ It should be fully compatible with any interpreter that is compliant with Ruby 1
 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
+```ruby    
 require 'concurrent'
 require 'thread'   # for Queue
 require 'open-uri' # for open(uri)
@@ -140,6 +143,7 @@ task.value #=> 25.96
 * [Ravil Bayramgalin](https://github.com/brainopia)
 * [Larry Lv](https://github.com/larrylv)
 * [Giuseppe Capizzi](https://github.com/gcapizzi)
+* [Bill Dueber](https://github.com/billdueber)
 * [Brian Shirai](https://github.com/brixen)
 * [Chip Miller](https://github.com/chip-miller)
 * [Jamie Hodge](https://github.com/jamiehodge)
@@ -157,6 +161,6 @@ task.value #=> 25.96
 
 *Concurrent Ruby* is free software released under the [MIT License](http://www.opensource.org/licenses/MIT).
 
-The *Concurrent Ruby* [logo](https://github.com/jdantonio/concurrent-ruby/wiki/Logo)
+The *Concurrent Ruby* [logo](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Logo)
 was designed by [David Jones](https://twitter.com/zombyboy).
 It is Copyright &copy; 2014 [Jerry D'Antonio](https://twitter.com/jerrydantonio). All Rights Reserved.

data/lib/concurrent/actress/ad_hoc.rb

@@ -1,5 +1,11 @@
 module Concurrent
   module Actress
+    # Allows quick creation of actors with behaviour defined by blocks.
+    # @example ping
+    #   AdHoc.spawn :forward, an_actor do |where|
+    #     # this block has to return proc defining #on_message behaviour
+    #     -> message { where.tell message  }
+    #   end
     class AdHoc
       include Context
       def initialize(*args, &initializer)

data/lib/concurrent/actress/context.rb

@@ -1,7 +1,8 @@
 module Concurrent
   module Actress
 
-    # module used to define actor behaviours
+    # This module is used to define actors. It can be included in any class,
+    # only requirement is to override {Context#on_message} method.
     # @example ping
     #  class Ping
     #    include Context
@@ -26,10 +27,6 @@ module Concurrent
         raise NotImplementedError
       end
 
-      def logger
-        core.logger
-      end
-
       # @api private
       def on_envelope(envelope)
         @envelope = envelope
@@ -53,9 +50,14 @@ module Concurrent
         core.terminate!
       end
 
+      # delegates to core.log
+      # @see Logging#log
+      def log(level, progname, message = nil, &block)
+        core.log(level, progname, message, &block)
+      end
+
       private
 
-      # @api private
       def initialize_core(core)
         @core = Type! core, Core
       end
@@ -71,12 +73,12 @@ module Concurrent
       end
 
       module ClassMethods
-        # behaves as {Actress.spawn} but class_name is omitted
+        # behaves as {Concurrent::Actress.spawn} but class_name is auto-inserted based on receiver
         def spawn(name_or_opts, *args, &block)
           Actress.spawn spawn_optionify(name_or_opts, *args), &block
         end
 
-        # behaves as {Actress.spawn!} but class_name is omitted
+        # behaves as {Concurrent::Actress.spawn!} but class_name is auto-inserted based on receiver
         def spawn!(name_or_opts, *args, &block)
           Actress.spawn! spawn_optionify(name_or_opts, *args), &block
         end

data/lib/concurrent/actress/core.rb

@@ -4,33 +4,50 @@ module Concurrent
     require 'set'
 
     # Core of the actor
-    # @api private
+    # @note Whole class should be considered private. An user should use {Context}s and {Reference}s only.
     # @note devel: core should not block on anything, e.g. it cannot wait on children to terminate
     #   that would eat up all threads in task pool and deadlock
     class Core
       include TypeCheck
       include Concurrent::Logging
 
-      attr_reader :reference, :name, :path, :executor, :terminated
+      # @!attribute [r] reference
+      #   @return [Reference] reference to this actor which can be safely passed around
+      # @!attribute [r] name
+      #   @return [String] the name of this instance, it should be uniq (not enforced right now)
+      # @!attribute [r] path
+      #   @return [String] a path of this actor. It is used for easier orientation and logging.
+      #     Path is constructed recursively with: `parent.path + self.name` up to a {Actress::ROOT},
+      #     e.g. `/an_actor/its_child`.
+      #     (It will also probably form a supervision path (failures will be reported up to parents)
+      #     in future versions.)
+      # @!attribute [r] executor
+      #   @return [Executor] which is used to process messages
+      # @!attribute [r] terminated
+      #   @return [Event] event which will become set when actor is terminated.
+      # @!attribute [r] actor_class
+      #   @return [Context] a class including {Context} representing Actor's behaviour
+      attr_reader :reference, :name, :path, :executor, :terminated, :actor_class
 
       # @option opts [String] name
       # @option opts [Reference, nil] parent of an actor spawning this one
-      # @option opts [Context] actress_class a class to be instantiated defining Actor's behaviour
-      # @option opts [Array<Object>] args arguments for actress_class instantiation
+      # @option opts [Context] actor_class a class to be instantiated defining Actor's behaviour
+      # @option opts [Array<Object>] args arguments for actor_class instantiation
       # @option opts [Executor] executor, default is `Concurrent.configuration.global_task_pool`
       # @option opts [IVar, nil] initialized, if present it'll be set or failed after {Context} initialization
       # @option opts [Proc, nil] logger a proc accepting (level, progname, message = nil, &block) params,
       #   can be used to hook actor instance to any logging system
       # @param [Proc] block for class instantiation
       def initialize(opts = {}, &block)
-        @mailbox    = Array.new
-        @one_by_one = OneByOne.new
+        @mailbox              = Array.new
+        @serialized_execution = SerializedExecution.new
         # noinspection RubyArgCount
-        @terminated = Event.new
-        @executor   = Type! opts.fetch(:executor, Concurrent.configuration.global_task_pool), Executor
-        @children   = Set.new
-        @reference  = Reference.new self
-        @name       = (Type! opts.fetch(:name), String, Symbol).to_s
+        @terminated           = Event.new
+        @executor             = Type! opts.fetch(:executor, Concurrent.configuration.global_task_pool), Executor
+        @children             = Set.new
+        @reference            = Reference.new self
+        @name                 = (Type! opts.fetch(:name), String, Symbol).to_s
+        @actor                = Concurrent::Atomic.new
 
         parent       = opts[:parent]
         @parent_core = (Type! parent, Reference, NilClass) && parent.send(:core)
@@ -43,14 +60,14 @@ module Concurrent
 
         @parent_core.add_child reference if @parent_core
 
-        @actress_class = actress_class = Child! opts.fetch(:class), Context
-        args           = opts.fetch(:args, [])
-        initialized    = Type! opts[:initialized], IVar, NilClass
+        @actor_class = actor_class = Child! opts.fetch(:class), Context
+        args         = opts.fetch(:args, [])
+        initialized  = Type! opts[:initialized], IVar, NilClass
 
         schedule_execution do
           begin
-            @actress = actress_class.new *args, &block
-            @actress.send :initialize_core, self
+            @actor.value = actor_class.new(*args, &block).
+                tap { |a| a.send :initialize_core, self }
             initialized.set true if initialized
           rescue => ex
             log ERROR, ex
@@ -113,6 +130,8 @@ module Concurrent
       # Terminates all its children, does not wait until they are terminated.
       def terminate!
         guard!
+        return nil if terminated?
+
         @children.each do |ch|
           ch.send(:core).tap { |core| core.send(:schedule_execution) { core.terminate! } }
         end
@@ -150,6 +169,11 @@ module Concurrent
         end
       end
 
+      # @return [Context]
+      def actor
+        @actor.value
+      end
+
       # Processes single envelope, calls #process_envelopes? at the end to ensure next envelope
       # scheduling.
       def receive_envelope
@@ -162,7 +186,7 @@ module Concurrent
 
         log DEBUG, "received #{envelope.message} from #{envelope.sender_path}"
 
-        result = @actress.on_envelope envelope
+        result = actor.on_envelope envelope
         envelope.ivar.set result unless envelope.ivar.nil?
 
         nil
@@ -178,14 +202,14 @@ module Concurrent
       # Schedules blocks to be executed on executor sequentially,
       # sets Actress.current
       def schedule_execution
-        @one_by_one.post(@executor) do
+        @serialized_execution.post(@executor) do
           begin
-            Thread.current[:__current_actress__] = reference
+            Thread.current[:__current_actor__] = reference
             yield
           rescue => e
             log FATAL, e
           ensure
-            Thread.current[:__current_actress__] = nil
+            Thread.current[:__current_actor__] = nil
           end
         end
 

data/lib/concurrent/actress/core_delegations.rb

@@ -31,7 +31,12 @@ module Concurrent
         core.executor
       end
 
+      def actor_class
+        core.actor_class
+      end
+
       alias_method :ref, :reference
+      alias_method :actress_class, :actor_class
     end
   end
 end

data/lib/concurrent/actress/envelope.rb

@@ -1,12 +1,24 @@
 module Concurrent
   module Actress
-    Envelope = Struct.new :message, :ivar, :sender do
+    class Envelope
       include TypeCheck
 
-      def initialize(message, ivar, sender)
-        super message,
-              (Type! ivar, IVar, NilClass),
-              (Type! sender, Reference, Thread)
+      # @!attribute [r] message
+      #   @return [Object] a message
+      # @!attribute [r] ivar
+      #   @return [IVar] an ivar which becomes resolved after message is processed
+      # @!attribute [r] sender
+      #   @return [Reference, Thread] an actor or thread sending the message
+      # @!attribute [r] address
+      #   @return [Reference] where this message will be delivered
+
+      attr_reader :message, :ivar, :sender, :address
+
+      def initialize(message, ivar, sender, address)
+        @message = message
+        @ivar    = Type! ivar, IVar, NilClass
+        @sender  = Type! sender, Reference, Thread
+        @address = Type! address, Reference
       end
 
       def sender_path
@@ -17,6 +29,10 @@ module Concurrent
         end
       end
 
+      def address_path
+        address.path
+      end
+
       def reject!(error)
         ivar.fail error unless ivar.nil?
       end

data/lib/concurrent/actress/reference.rb

@@ -2,8 +2,8 @@ module Concurrent
   module Actress
 
     # Reference is public interface of Actor instances. It is used for sending messages and can
-    # be freely passed around the program. It also provides some basic information about the actor
-    # see {CoreDelegations}
+    # be freely passed around the program. It also provides some basic information about the actor,
+    # see {CoreDelegations}.
     class Reference
       include TypeCheck
       include CoreDelegations
@@ -43,14 +43,14 @@ module Concurrent
         ask(message, ivar).value!
       end
 
-      # behaves as #tell when no ivar and as #ask when ivar
+      # behaves as {#tell} when no ivar and as {#ask} when ivar
       def message(message, ivar = nil)
-        core.on_envelope Envelope.new(message, ivar, Actress.current || Thread.current)
+        core.on_envelope Envelope.new(message, ivar, Actress.current || Thread.current, self)
         return ivar || self
       end
 
       def to_s
-        "#<#{self.class} #{path}>"
+        "#<#{self.class} #{path} (#{actor_class})>"
       end
 
       alias_method :inspect, :to_s

data/lib/concurrent/actress.rb

@@ -1,11 +1,133 @@
 require 'concurrent/configuration'
-require 'concurrent/executor/one_by_one'
+require 'concurrent/executor/serialized_execution'
 require 'concurrent/ivar'
 require 'concurrent/logging'
 
 module Concurrent
 
-  # {include:file:lib/concurrent/actress/doc.md}
+  # # Actor model
+  #
+  # -  Light-weighted.
+  # -  Inspired by Akka and Erlang.
+  #
+  # Actors are sharing a thread-pool by default which makes them very cheap to create and discard.
+  # Thousands of actors can be created allowing to brake the program to small maintainable pieces
+  # without breaking single responsibility principles.
+  #
+  # ## What is an actor model?
+  #
+  # [Wiki](http://en.wikipedia.org/wiki/Actor_model) says:
+  # The actor model in computer science is a mathematical model of concurrent computation
+  # that treats _actors_ as the universal primitives of concurrent digital computation:
+  # in response to a message that it receives, an actor can make local decisions,
+  # create more actors, send more messages, and determine how to respond to the next
+  # message received.
+  #
+  # ## Why?
+  #
+  # Concurrency is hard this is one of many ways how to simplify the problem.
+  # It is simpler to reason about actors then about locks (and all their possible states).
+  #
+  # ## How to use it
+  #
+  # {include:file:doc/actress/quick.out.rb}
+  #
+  # ## Messaging
+  #
+  # Messages are processed in same order as they are sent by a sender. It may interleaved with
+  # messages form other senders though. There is also a contract in actor model that
+  # messages sent between actors should be immutable. Gems like
+  #
+  # - [Algebrick](https://github.com/pitr-ch/algebrick) - Typed struct on steroids based on
+  #   algebraic types and pattern matching
+  # - [Hamster](https://github.com/hamstergem/hamster) - Efficient, Immutable, Thread-Safe
+  #   Collection classes for Ruby
+  #
+  # are very useful.
+  #
+  # ## Architecture
+  #
+  # Actors are running on shared thread poll which allows user to create many actors cheaply.
+  # Downside is that these actors cannot be directly used to do IO or other blocking operations.
+  # Blocking operations could starve the `default_task_pool`. However there are two options:
+  #
+  # - Create an regular actor which will schedule blocking operations in `global_operation_pool`
+  #   (which is intended for blocking operations) sending results back to self in messages.
+  # - Create an actor using `global_operation_pool` instead of `global_task_pool`, e.g.
+  #   `AnIOActor.spawn name: :blocking, executor: Concurrent.configuration.global_operation_pool`.
+  #
+  # Each actor is composed from 3 objects:
+  #
+  # ### {Reference}
+  # {include:Actress::Reference}
+  #
+  # ### {Core}
+  # {include:Actress::Core}
+  #
+  # ### {Context}
+  # {include:Actress::Context}
+  #
+  # ## Speed
+  #
+  # Simple benchmark Actress vs Celluloid, the numbers are looking good
+  # but you know how it is with benchmarks. Source code is in
+  # `examples/actress/celluloid_benchmark.rb`. It sends numbers between x actors
+  # and adding 1 until certain limit is reached.
+  #
+  # Benchmark legend:
+  #
+  # - mes.  - number of messages send between the actors
+  # - act.  - number of actors exchanging the messages
+  # - impl. - which gem is used
+  #
+  # ### JRUBY
+  #
+  #     Rehearsal --------------------------------------------------------
+  #     50000    2 actress    24.110000   0.800000  24.910000 (  7.728000)
+  #     50000    2 celluloid  28.510000   4.780000  33.290000 ( 14.782000)
+  #     50000  500 actress    13.700000   0.280000  13.980000 (  4.307000)
+  #     50000  500 celluloid  14.520000  11.740000  26.260000 ( 12.258000)
+  #     50000 1000 actress    10.890000   0.220000  11.110000 (  3.760000)
+  #     50000 1000 celluloid  15.600000  21.690000  37.290000 ( 18.512000)
+  #     50000 1500 actress    10.580000   0.270000  10.850000 (  3.646000)
+  #     50000 1500 celluloid  14.490000  29.790000  44.280000 ( 26.043000)
+  #     --------------------------------------------- total: 201.970000sec
+  #     
+  #      mes. act.      impl.      user     system      total        real
+  #     50000    2 actress     9.820000   0.510000  10.330000 (  5.735000)
+  #     50000    2 celluloid  10.390000   4.030000  14.420000 (  7.494000)
+  #     50000  500 actress     9.880000   0.200000  10.080000 (  3.310000)
+  #     50000  500 celluloid  12.430000  11.310000  23.740000 ( 11.727000)
+  #     50000 1000 actress    10.590000   0.190000  10.780000 (  4.029000)
+  #     50000 1000 celluloid  14.950000  23.260000  38.210000 ( 20.841000)
+  #     50000 1500 actress    10.710000   0.250000  10.960000 (  3.892000)
+  #     50000 1500 celluloid  13.280000  30.030000  43.310000 ( 24.620000) (1)
+  #
+  # ### MRI 2.1.0
+  #
+  #     Rehearsal --------------------------------------------------------
+  #     50000    2 actress     4.640000   0.080000   4.720000 (  4.852390)
+  #     50000    2 celluloid   6.110000   2.300000   8.410000 (  7.898069)
+  #     50000  500 actress     6.260000   2.210000   8.470000 (  7.400573)
+  #     50000  500 celluloid  10.250000   4.930000  15.180000 ( 14.174329)
+  #     50000 1000 actress     6.300000   1.860000   8.160000 (  7.303162)
+  #     50000 1000 celluloid  12.300000   7.090000  19.390000 ( 17.962621)
+  #     50000 1500 actress     7.410000   2.610000  10.020000 (  8.887396)
+  #     50000 1500 celluloid  14.850000  10.690000  25.540000 ( 24.489796)
+  #     ---------------------------------------------- total: 99.890000sec
+  #     
+  #      mes. act.      impl.      user     system      total        real
+  #     50000    2 actress     4.190000   0.070000   4.260000 (  4.306386)
+  #     50000    2 celluloid   6.490000   2.210000   8.700000 (  8.280051)
+  #     50000  500 actress     7.060000   2.520000   9.580000 (  8.518707)
+  #     50000  500 celluloid  10.550000   4.980000  15.530000 ( 14.699962)
+  #     50000 1000 actress     6.440000   1.870000   8.310000 (  7.571059)
+  #     50000 1000 celluloid  12.340000   7.510000  19.850000 ( 18.793591)
+  #     50000 1500 actress     6.720000   2.160000   8.880000 (  7.929630)
+  #     50000 1500 celluloid  14.140000  10.130000  24.270000 ( 22.775288) (1)
+  #
+  # *Note (1):* Celluloid is using thread per actor so this bench is creating about 1500
+  # native threads. Actress is using constant number of threads.
   module Actress
 
     require 'concurrent/actress/type_check'
@@ -20,7 +142,7 @@ module Concurrent
 
     # @return [Reference, nil] current executing actor if any
     def self.current
-      Thread.current[:__current_actress__]
+      Thread.current[:__current_actor__]
     end
 
     # implements ROOT
@@ -39,10 +161,26 @@ module Concurrent
     # A root actor, a default parent of all actors spawned outside an actor
     ROOT = Core.new(parent: nil, name: '/', class: Root).reference
 
+    # Spawns a new actor.
+    #
+    # @example simple
+    #   Actress.spawn(AdHoc, :ping1) { -> message { message } }
+    #
+    # @example complex
+    #   Actress.spawn name:     :ping3,
+    #                 class:    AdHoc,
+    #                 args:     [1]
+    #                 executor: Concurrent.configuration.global_task_pool do |add|
+    #     lambda { |number| number + add }
+    #   end
+    #
     # @param block for actress_class instantiation
     # @param args see {.spawn_optionify}
+    # @return [Reference] never the actual actor
     def self.spawn(*args, &block)
-      warn '[EXPERIMENTAL] A full release of `Actress`, renamed `Actor`, is expected in the 0.7.0 release.'
+      experimental_acknowledged? or
+          warn '[EXPERIMENTAL] A full release of `Actress`, renamed `Actor`, is expected in the 0.7.0 release.'
+
       if Actress.current
         Core.new(spawn_optionify(*args).merge(parent: Actress.current), &block).reference
       else
@@ -52,13 +190,12 @@ module Concurrent
 
     # as {.spawn} but it'll raise when Actor not initialized properly
     def self.spawn!(*args, &block)
-      warn '[EXPERIMENTAL] A full release of `Actress`, renamed `Actor`, is expected in the 0.7.0 release.'
       spawn(spawn_optionify(*args).merge(initialized: ivar = IVar.new), &block).tap { ivar.no_error! }
     end
 
     # @overload spawn_optionify(actress_class, name, *args)
     #   @param [Context] actress_class to be spawned
-    #   @param [String, Symbol] name of the instance, it's used to generate the path of the actor
+    #   @param [String, Symbol] name of the instance, it's used to generate the {Core#path} of the actor
     #   @param args for actress_class instantiation
     # @overload spawn_optionify(opts)
     #   see {Core#initialize} opts
@@ -71,5 +208,14 @@ module Concurrent
           args:  args[2..-1] }
       end
     end
+
+    # call this to disable experimental warning
+    def self.i_know_it_is_experimental!
+      @experimental_acknowledged = true
+    end
+
+    def self.experimental_acknowledged?
+      !!@experimental_acknowledged
+    end
   end
 end