Merge remote-tracking branch 'upstream/master' into actress

* upstream/master: (14 commits)
  Added another dataflow example from the wiki.
  ...

Author: pitr-ch

CHANGELOG.md

@@ -0,0 +1,136 @@
+### Upcoming Release v0.7.1 (TBD)
+
+Please see the [roadmap](https://github.com/ruby-concurrency/concurrent-ruby/issues/142) for more information on the next planned release.
+
+* Added `flat_map` method to `Promise`
+* Added `zip` method to `Promise`
+* Fixed bug with logging in `Actor`
+* Improvements to `Promise` tests
+* Removed actor-experimental warning
+* Added an `IndirectImmediateExecutor` class
+* Allow disabling auto termination of global executors
+* Fix thread leaking in `ThreadLocalVar` (uses `Ref` gem on non-JRuby systems)
+* Fix thread leaking when pruning pure-Ruby thread pools
+* Prevent `Actor` from using an `ImmediateExecutor` (causes deadlock)
+* Added missing synchronizations to `TimerSet`
+* Fixed bug with return value of `Concurrent::Actor::Utils::Pool#ask`
+* Removed confusing warning when not using native extenstions
+* Improved documentation
+
+## Current Release v0.7.0 (13 August 2014)
+
+* Merge the [atomic](https://github.com/ruby-concurrency/atomic) gem
+  - Pure Ruby `MutexAtomic` atomic reference class
+  - Platform native atomic reference classes `CAtomic`, `JavaAtomic`, and `RbxAtomic`
+  - Automated [build process](https://github.com/ruby-concurrency/rake-compiler-dev-box)
+  - Fat binary releases for [multiple platforms](https://rubygems.org/gems/concurrent-ruby/versions) including Windows (32/64), Linux (32/64), OS X (64-bit), Solaris (64-bit), and JRuby
+* C native `CAtomicBoolean`
+* C native `CAtomicFixnum`
+* Refactored intermittently failing tests
+* Added `dataflow!` and `dataflow_with!` methods to match `Future#value!` method
+* Better handling of timeout in `Agent`
+* Actor Improvements
+  - Fine-grained implementation using chain of behaviors. Each behavior is responsible for single aspect like: `Termination`, `Pausing`, `Linking`, `Supervising`, etc. Users can create custom Actors easily based on their needs.
+  - Supervision was added. `RestartingContext` will pause on error waiting on its supervisor to decide what to do next ( options are `:terminate!`, `:resume!`, `:reset!`, `:restart!`). Supervising behavior also supports strategies `:one_for_one` and `:one_for_all`.
+  - Linking was added to be able to monitor actor's events like: `:terminated`, `:paused`, `:restarted`, etc.
+  - Dead letter routing added. Rejected envelopes are collected in a configurable actor (default: `Concurrent::Actor.root.ask!(:dead_letter_routing)`)
+  - Old `Actor` class removed and replaced by new implementation previously called `Actress`. `Actress` was kept as an alias for `Actor` to keep compatibility.
+  - `Utils::Broadcast` actor which allows Publish–subscribe pattern.
+* More executors for managing serialized operations
+  - `SerializedExecution` mixin module
+  - `SerializedExecutionDelegator` for serializing *any* executor
+* Updated `Async` with serialized execution
+* Updated `ImmediateExecutor` and `PerThreadExecutor` with full executor service lifecycle
+* Added a `Delay` to root `Actress` initialization 
+* Minor bug fixes to thread pools
+* Refactored many intermittently failing specs
+* Removed Java interop warning `executor.rb:148 warning: ambiguous Java methods found, using submit(java.lang.Runnable)`
+* Fixed minor bug in `RubyCachedThreadPool` overflow policy
+* Updated tests to use [RSpec 3.0](http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3)
+* Removed deprecated `Actor` class
+* Better support for Rubinius
+
+### Release v0.6.1 (14 June 2014)
+
+* Many improvements to `Concurrent::Actress`
+* Bug fixes to `Concurrent::RubyThreadPoolExecutor`
+* Fixed several brittle tests
+* Moved documentation to http://ruby-concurrency.github.io/concurrent-ruby/frames.html
+
+### Release v0.6.0 (25 May 2014)
+
+* Added `Concurrent::Observable` to encapsulate our thread safe observer sets
+* Improvements to new `Channel`
+* Major improvements to `CachedThreadPool` and `FixedThreadPool`
+* Added `SingleThreadExecutor`
+* Added `Current::timer` function
+* Added `TimerSet` executor
+* Added `AtomicBoolean`
+* `ScheduledTask` refactoring
+* Pure Ruby and JRuby-optimized `PriorityQueue` classes
+* Updated `Agent` behavior to more closely match Clojure
+* Observer sets support block callbacks to the `add_observer` method
+* New algorithm for thread creation in `RubyThreadPoolExecutor`
+* Minor API updates to `Event`
+* Rewritten `TimerTask` now an `Executor` instead of a `Runnable`
+* Fixed many brittle specs
+* Renamed `FixedThreadPool` and `CachedThreadPool` to `RubyFixedThreadPool` and `RubyCachedThreadPool`
+* Created JRuby optimized `JavaFixedThreadPool` and `JavaCachedThreadPool`
+* Consolidated fixed thread pool tests into `spec/concurrent/fixed_thread_pool_shared.rb` and  `spec/concurrent/cached_thread_pool_shared.rb`
+* `FixedThreadPool` now subclasses `RubyFixedThreadPool` or `JavaFixedThreadPool` as appropriate
+* `CachedThreadPool` now subclasses `RubyCachedThreadPool` or `JavaCachedThreadPool` as appropriate
+* New `Delay` class
+* `Concurrent::processor_count` helper function
+* New `Async` module
+* Renamed `NullThreadPool` to `PerThreadExecutor`
+* Deprecated `Channel` (we are planning a new implementation based on [Go](http://golangtutorials.blogspot.com/2011/06/channels-in-go.html))
+* Added gem-level [configuration](http://robots.thoughtbot.com/mygem-configure-block)
+* Deprecated `$GLOBAL_THREAD_POOL` in lieu of gem-level configuration
+* Removed support for Ruby [1.9.2](https://www.ruby-lang.org/en/news/2013/12/17/maintenance-of-1-8-7-and-1-9-2/)
+* New `RubyThreadPoolExecutor` and `JavaThreadPoolExecutor` classes
+* All thread pools now extend the appropriate thread pool executor classes
+* All thread pools now support `:overflow_policy` (based on Java's [reject policies](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ThreadPoolExecutor.html))
+* Deprecated `UsesGlobalThreadPool` in lieu of explicit `:executor` option (dependency injection) on `Future`, `Promise`, and `Agent`
+* Added `Concurrent::dataflow_with(executor, *inputs)` method to support executor dependency injection for dataflow
+* Software transactional memory with `TVar` and `Concurrent::atomically`
+* First implementation of [new, high-performance](https://github.com/ruby-concurrency/concurrent-ruby/pull/49) `Channel`
+* `Actor` is deprecated in favor of new experimental actor implementation [#73](https://github.com/ruby-concurrency/concurrent-ruby/pull/73). To avoid namespace collision it is living in `Actress` namespace until `Actor` is removed in next release.
+
+### Release v0.5.0
+
+This is the most significant release of this gem since its inception. This release includes many improvements and optimizations. It also includes several bug fixes. The major areas of focus for this release were:
+
+* Stability improvements on Ruby versions with thread-level parallelism ([JRuby](http://jruby.org/) and [Rubinius](http://rubini.us/))
+* Creation of new low-level concurrency abstractions
+* Internal refactoring to use the new low-level abstractions
+
+Most of these updates had no effect on the gem API. There are a few notable exceptions which were unavoidable. Please read the [release notes](API-Updates-in-v0.5.0) for more information.
+
+Specific changes include:
+
+* New class `IVar`
+* New class `MVar`
+* New class `ThreadLocalVar`
+* New class `AtomicFixnum`
+* New class method `dataflow`
+* New class `Condition`
+* New class `CountDownLatch`
+* New class `DependencyCounter`
+* New class `SafeTaskExecutor`
+* New class `CopyOnNotifyObserverSet`
+* New class `CopyOnWriteObserverSet`
+* `Future` updated with `execute` API
+* `ScheduledTask` updated with `execute` API
+* New `Promise` API
+* `Future` now extends `IVar`
+* `Postable#post?` now returns an `IVar`
+* Thread safety fixes to `Dereferenceable`
+* Thread safety fixes to `Obligation`
+* Thread safety fixes to `Supervisor`
+* Thread safety fixes to `Event`
+* Various other thread safety (race condition) fixes
+* Refactored brittle tests
+* Implemented pending tests
+* Added JRuby and Rubinius as Travis CI build targets
+* Added [CodeClimate](https://codeclimate.com/) code review
+* Improved YARD documentation

README.md

@@ -1,5 +1,5 @@
 # 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) [![License](http://img.shields.io/license/MIT.png?color=green)](http://opensource.org/licenses/MIT) [![Gitter chat](https://badges.gitter.im/ruby-concurrency/concurrent-ruby.png)](https://gitter.im/ruby-concurrency/concurrent-ruby)
+[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.svg)](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://img.shields.io/coveralls/ruby-concurrency/concurrent-ruby/master.svg)](https://coveralls.io/r/ruby-concurrency/concurrent-ruby) [![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.svg)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby) [![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.svg)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby) [![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.svg)](https://gemnasium.com/ruby-concurrency/concurrent-ruby) [![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT) [![Gitter chat](http://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/ruby-concurrency/concurrent-ruby)
 
 <table>
   <tr>
@@ -30,7 +30,7 @@
       </p>
     </td>
     <td align="right" valign="top">
-      <img src="https://raw.githubusercontent.com/wiki/ruby-concurrency/concurrent-ruby/logo/concurrent-ruby-logo-300x300.png"/>
+      <img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc/logo/concurrent-ruby-logo-300x300.png"/>
     </td>
   </tr>
 </table>
@@ -74,8 +74,9 @@ This gem adheres to the rules of [semantic versioning](http://semver.org/).
 ### Supported Ruby versions
 
 MRI 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 interpreter that is compliant with Ruby 1.9.3 or newer.
+Although native code is used for performance optimizations on some platforms, all functionality
+is available in pure Ruby. This gem should be fully compatible with any interpreter that is
+compliant with Ruby 1.9.3 or newer.
 
 ### Examples
 
@@ -163,7 +164,6 @@ The following gem builds will be built at every release:
 * concurrent-ruby-x.y.z-x86_64-linux.gem (Linux 64-bit)
 * concurrent-ruby-x.y.z-x86-mingw32.gem (Windows 32-bit)
 * concurrent-ruby-x.y.z-x64-mingw32.gem (Windows 64-bit)
-* concurrent-ruby-x.y.z-x86_64-darwin-13.gem (OS X)
 * concurrent-ruby-x.y.z-x86-solaris-2.11.gem (Solaris)
 
 ### Installing

concurrent-ruby.gemspec

@@ -31,4 +31,8 @@ Gem::Specification.new do |s|
   end
 
   s.required_ruby_version = '>= 1.9.3'
+
+  unless defined?(JRUBY_VERSION)
+    s.add_dependency 'ref', '~> 1.0.5'
+  end
 end

doc/agent.md

@@ -0,0 +1,82 @@
+`Agent`s are inspired by [Clojure's](http://clojure.org/) [agent](http://clojure.org/agents) function. An `Agent` is a single atomic value that represents an identity. The current value of the `Agent` can be requested at any time (`deref`). Each `Agent` has a work queue and operates on the global thread pool (see below). Consumers can `post` code blocks to the `Agent`. The code block (function) will receive the current value of the `Agent` as its sole parameter. The return value of the block will become the new value of the `Agent`. `Agent`s support two error handling modes: fail and continue. A good example of an `Agent` is a shared incrementing counter, such as the score in a video game. 
+
+An `Agent` must be initialize with an initial value. This value is always accessible via the `value` (or `deref`) methods. Code blocks sent to the `Agent` will be processed in the order received. As each block is processed the current value is updated with the result from the block. This update is an atomic operation so a `deref` will never block and will always return the current value. 
+
+When an `Agent` is created it may be given an optional `validate` block and zero or more `rescue` blocks. When a new value is calculated the value will be checked against the validator, if present. If the validator returns `true` the new value will be accepted. If it returns `false` it will be rejected. If a block raises an exception during execution the list of `rescue` blocks will be seacrhed in order until one matching the current exception is found. That `rescue` block will then be called an passed the exception object. If no matching `rescue` block is found, or none were configured, then the exception will be suppressed. 
+
+`Agent`s also implement Ruby's [Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html). Code that observes an `Agent` will receive a callback with the new value any time the value is changed. 
+
+## Copy Options
+
+Object references in Ruby are mutable. This can lead to serious problems when the value of an `Agent` is a mutable reference. Which is always the case unless the value is a `Fixnum`, `Symbol`, or similar "primative" data type. Each `Agent` instance can be configured with a few options that can help protect the program from potentially dangerous operations. Each of these options can be optionally set when the `Agent` is created: 
+
+* `:dup_on_deref` when true the `Agent` will call the `#dup` method on the `value` object every time the `#value` methid is called (default: false)
+* `:freeze_on_deref` when true the `Agent` will call the `#freeze` method on the `value` object every time the `#value` method is called (default: false)
+* `:copy_on_deref` when given a `Proc` object the `Proc` will be run every time   the `#value` method is called. The `Proc` will be given the current `value` as   its only parameter and the result returned by the block will be the return   value of the `#value` call. When `nil` this option will be ignored (default:   nil)
+
+## Examples
+
+A simple example:
+
+```ruby
+require 'concurrent'
+
+score = Concurrent::Agent.new(10)
+score.value #=> 10
+
+score << proc{|current| current + 100 }
+sleep(0.1)
+score.value #=> 110
+
+score << proc{|current| current * 2 }
+sleep(0.1)
+score.value #=> 220
+
+score << proc{|current| current - 50 }
+sleep(0.1)
+score.value #=> 170
+```
+
+With validation and error handling:
+
+```ruby
+score = Concurrent::Agent.new(0).validate{|value| value <= 1024 }.
+          rescue(NoMethodError){|ex| puts "Bam!" }.
+          rescue(ArgumentError){|ex| puts "Pow!" }.
+          rescue{|ex| puts "Boom!" }
+score.value #=> 0
+
+score << proc{|current| current + 2048 }
+sleep(0.1)
+score.value #=> 0
+
+score << proc{|current| raise ArgumentError }
+sleep(0.1)
+#=> puts "Pow!"
+score.value #=> 0
+
+score << proc{|current| current + 100 }
+sleep(0.1)
+score.value #=> 100
+```
+
+With observation:
+
+```ruby
+bingo = Class.new{
+  def update(time, score)
+    puts "Bingo! [score: #{score}, time: #{time}]" if score >= 100
+  end
+}.new
+
+score = Concurrent::Agent.new(0)
+score.add_observer(bingo)
+
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+
+sleep(1)
+#=> Bingo! [score: 120, time: 2013-07-22 21:26:08 -0400]
+```