Merge branch 'master' into tvars.

Author: chrisseaton

Gemfile

@@ -5,13 +5,14 @@ gemspec
 group :development do
   gem 'rake', '~> 10.1.1'
   gem 'countloc', '~> 0.4.0', platforms: :mri
+  gem 'yard', '~> 0.8.7.3'
+  gem 'inch', '~> 0.3.2', platforms: :mri
 end
 
 group :testing do
   gem 'rspec', '~> 2.14.1'
   gem 'simplecov', '~> 0.8.2'
   gem 'coveralls', '~> 0.7.0', require: false
-  gem 'yard', '~> 0.8.7.3'
   gem 'faker', '~> 1.3.0'
   gem 'timecop', '~> 0.7.1'
 end

README.md

@@ -1,26 +1,39 @@
 # 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) [![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://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)
 
 ***NOTE:*** *A few API updates in v0.5.0 are not backward-compatible. Please see the [release notes](https://github.com/jdantonio/concurrent-ruby/wiki/API-Updates-in-v0.5.0).*
 
+<table>
+<tr>
+<td align="left" valign="top">
+<p>
 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),
+<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:
-
-* 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
+<ul>
+<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>
+</table>
 
 ## Features & Documentation
 
@@ -29,11 +42,13 @@ or the [API documentation](http://rubydoc.info/github/jdantonio/concurrent-ruby/
 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 categories:
+into several general groups:
 
-* Asynchronous concurrency abstractions including [Actor](https://github.com/jdantonio/concurrent-ruby/wiki/Actor),
-  [Agent](https://github.com/jdantonio/concurrent-ruby/wiki/Agent), [Channel](https://github.com/jdantonio/concurrent-ruby/wiki/Channel),
-  [Future](https://github.com/jdantonio/concurrent-ruby/wiki/Future), [Promise](https://github.com/jdantonio/concurrent-ruby/wiki/Promise),
+* 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),
   [ScheculedTask](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
@@ -53,73 +68,67 @@ This gem adheres to the rules of [semantic versioning](http://semver.org/).
 
 ### Supported Ruby versions
 
-MRI 1.9.2, 1.9.3, 2.0, 2.1, JRuby (1.9 mode), and Rubinius 2.x. This library is pure Ruby and has no gem dependencies.
+MRI 1.9.2, 1.9.3, 2.0, 2.1, JRuby (1.9 mode), and Rubinius 2.x.
+This library is pure Ruby and has no gem dependencies.
 It should be fully compatible with any Ruby interpreter that is 1.9.x compliant.
 
-### Example
+### Examples
 
 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'
-
-class EchoActor < Concurrent::Actor
-  def act(*message)
-    puts "#{message} handled by #{self}"
+require 'thread'   # for Queue
+require 'open-uri' # for open(uri)
+
+class Ticker
+  def get_year_end_closing(symbol, year)
+    uri = "http://ichart.finance.yahoo.com/table.csv?s=#{symbol}&a=11&b=01&c=#{year}&d=11&e=31&f=#{year}&g=m"
+    data = open(uri) {|f| f.collect{|line| line.strip } }
+    data[1].split(',')[4].to_f
   end
 end
 
-mailbox, pool = EchoActor.pool(5)
-
-timer_proc = proc do
-  mailbox.post(Faker::Company.bs)
-end
-
-t1 = Concurrent::TimerTask.new(execution_interval: rand(5)+1, &timer_proc)
-t2 = Concurrent::TimerTask.new(execution_interval: rand(5)+1, &timer_proc)
-
-overlord = Concurrent::Supervisor.new
-
-overlord.add_worker(t1)
-overlord.add_worker(t2)
-pool.each{|actor| overlord.add_worker(actor)}
-
-overlord.run!
-
-#=> ["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>
-
-overlord.stop
+# Future
+price = Concurrent::Future.execute{ Ticker.new.get_year_end_closing('TWTR', 2013) }
+price.state #=> :pending
+sleep(1)    # do other stuff
+price.value #=> 63.65
+price.state #=> :fulfilled
+
+# Promise
+prices = Concurrent::Promise.new{ puts Ticker.new.get_year_end_closing('AAPL', 2013) }.
+           then{ puts Ticker.new.get_year_end_closing('MSFT', 2013) }.
+           then{ puts Ticker.new.get_year_end_closing('GOOG', 2013) }.
+           then{ puts Ticker.new.get_year_end_closing('AMZN', 2013) }.execute
+prices.state #=> :pending
+sleep(1)     # do other stuff
+#=> 561.02
+#=> 37.41
+#=> 1120.71
+#=> 398.79
+
+# ScheduledTask
+task = Concurrent::ScheduledTask.execute(2){ Ticker.new.get_year_end_closing('INTC', 2013) }
+task.state #=> :pending
+sleep(3)   # do other stuff
+task.value #=> 25.96
+
+# Async
+ticker = Ticker.new
+ticker.extend(Concurrent::Async)
+hpq = ticker.async.get_year_end_closing('HPQ', 2013)
+ibm = ticker.await.get_year_end_closing('IBM', 2013)
+hpq.value #=> 27.98
+ibm.value #=> 187.57
 ```
 
-### Disclaimer
-
-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
-
 ## Contributors
 
 * [Michele Della Torre](https://github.com/mighe)
 * [Chris Seaton](https://github.com/chrisseaton)
+* [Lucas Allan](https://github.com/lucasallan)
 * [Giuseppe Capizzi](https://github.com/gcapizzi)
 * [Brian Shirai](https://github.com/brixen)
 * [Chip Miller](https://github.com/chip-miller)
@@ -138,3 +147,6 @@ These tools will help ease the burden, but at the end of the day it is essential
 
 *Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
 It is free software released under the [MIT License](http://www.opensource.org/licenses/MIT).
+
+The *Concurrent Ruby* logo was designed by [David Jones](https://twitter.com/zombyboy).
+It is Copyright &copy; 2014 Jerry D'Antonio. All Rights Reserved.

lib/concurrent.rb

@@ -1,4 +1,5 @@
 require 'concurrent/version'
+require 'concurrent/configuration'
 
 require 'concurrent/atomic'
 require 'concurrent/count_down_latch'
@@ -10,14 +11,16 @@
 
 require 'concurrent/actor'
 require 'concurrent/agent'
-require 'concurrent/channel'
+require 'concurrent/async'
 require 'concurrent/dataflow'
+require 'concurrent/delay'
 require 'concurrent/dereferenceable'
 require 'concurrent/event'
 require 'concurrent/future'
 require 'concurrent/mvar'
 require 'concurrent/obligation'
 require 'concurrent/postable'
+require 'concurrent/processor_count'
 require 'concurrent/promise'
 require 'concurrent/runnable'
 require 'concurrent/scheduled_task'
@@ -28,11 +31,12 @@
 require 'concurrent/tvar'
 require 'concurrent/utilities'
 
-require 'concurrent/global_thread_pool'
-
 require 'concurrent/cached_thread_pool'
 require 'concurrent/fixed_thread_pool'
 require 'concurrent/immediate_executor'
+require 'concurrent/per_thread_executor'
+require 'concurrent/thread_pool_executor'
+require 'concurrent/uses_global_thread_pool'
 
 # Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
 # F#, C#, Java, and classic concurrency patterns.

lib/concurrent/actor.rb

@@ -119,6 +119,8 @@ module Concurrent
   #   
   #   ping << :pong
   #
+  # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
+  #
   # @see http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
   class Actor
     include Observable
@@ -174,6 +176,8 @@ def initialize(queue)
     #   #=> [6] handled by #<EchoActor:0x007fc8014fb8b8>
     #   #=> [7] handled by #<EchoActor:0x007fc8014fb818>
     #   #=> [8] handled by #<EchoActor:0x007fc8014fb890>
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def self.pool(count, *args, &block)
       raise ArgumentError.new('count must be greater than zero') unless count > 0
       mailbox = Queue.new
@@ -202,24 +206,32 @@ def self.pool(count, *args, &block)
     # @return [Object] the result obtained when the message is successfully processed
     #
     # @raise NotImplementedError unless overridden in the +Actor+ subclass
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     # 
     # @!visibility public
     def act(*message)
       raise NotImplementedError.new("#{self.class} does not implement #act")
     end
 
     # @!visibility private
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_run # :nodoc:
       queue.clear
     end
 
     # @!visibility private
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_stop # :nodoc:
       queue.clear
       queue.push(:stop)
     end
 
     # @!visibility private
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_task # :nodoc:
       package = queue.pop
       return if package == :stop
@@ -247,6 +259,8 @@ def on_task # :nodoc:
     end
 
     # @!visibility private
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_error(time, msg, ex) # :nodoc:
     end
   end

lib/concurrent/agent.rb

@@ -2,7 +2,7 @@
 require 'observer'
 
 require 'concurrent/dereferenceable'
-require 'concurrent/global_thread_pool'
+require 'concurrent/uses_global_thread_pool'
 require 'concurrent/utilities'
 
 module Concurrent