Merge branch 'master' into actress

* master: (41 commits)
  Attempt to improve Dereferenceable shared specs.
  ...

Author: pitr-ch

.rspec

@@ -1,4 +1,3 @@
 --require spec_helper
 --color
---backtrace
 --format documentation

.yardopts

@@ -1,5 +1,4 @@
---protected
---private
+--no-private
 --embed-mixins
 --output-dir ./yardoc
 --markup markdown

Gemfile

@@ -18,7 +18,9 @@ end
 
 group :testing do
   gem 'rspec', '~> 3.2.0'
+  gem 'timecop', '~> 0.7.3'
+
+  # Coverage
   gem 'simplecov', '~> 0.10.0', :require => false
   gem 'coveralls', '~> 0.8.1', :require => false
-  gem 'timecop', '~> 0.7.3'
 end

README.md

@@ -53,6 +53,7 @@ This library contains a variety of concurrency abstractions at high and low leve
 ### High-level, general-purpose asynchronous concurrency abstractions
 
 * [Async](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Async.html): A mixin module that provides simple asynchronous behavior to any standard class/object or object.
+* [Atom](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Atom.html): A way to manage shared, synchronous, independent state.
 * [Future](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Future.html): An asynchronous operation that produces a value.
   * [Dataflow](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#dataflow-class_method): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
 * [Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html): Similar to Futures, with more features.

Rakefile

@@ -1,5 +1,7 @@
 #!/usr/bin/env rake
 
+$:.push File.join(File.dirname(__FILE__), 'lib')
+
 require 'concurrent/version'
 require 'concurrent/native_extensions'
 

doc/agent.md

@@ -2,11 +2,37 @@
 require 'concurrent'
 require 'concurrent-edge'
 
+# require 'ruby-prof'
+#
+# result = RubyProf.profile do
+#   1000.times do
+#     head    = Concurrent.future { 1 }
+#     branch1 = head.then(&:succ)
+#     branch2 = head.then(&:succ).then(&:succ)
+#     branch3 = head.then(&:succ).then(&:succ).then(&:succ)
+#     Concurrent.join(branch1, branch2, branch3).then { |(a, b, c)| a + b + c }.value!
+#   end
+# end
+#
+# printer = RubyProf::FlatPrinter.new(result)
+# printer.print(STDOUT)
+#
+# printer = RubyProf::GraphPrinter.new(result)
+# printer.print(STDOUT, {})
+#
+# exit
+
 scale  = 1
 time   = 10 * scale
 warmup = 2 * scale
 warmup *= 10 if Concurrent.on_jruby?
 
+Benchmark.ips(time, warmup) do |x|
+  x.report('flat-old') { Concurrent::Promise.execute { 1 }.flat_map { |v| Concurrent::Promise.execute { v + 2 } }.value! }
+  x.report('flat-new') { Concurrent.future(:fast) { 1 }.then { |v| Concurrent.future(:fast) { v+ 1 } }.flat.value! }
+  x.compare!
+end
+
 Benchmark.ips(time, warmup) do |x|
   x.report('status-old') { f = Concurrent::Promise.execute { nil }; 100.times { f.complete? } }
   x.report('status-new') { f = Concurrent.future(:fast) { nil }; 100.times { f.completed? } }

doc/async.md

@@ -13,11 +13,13 @@
 require 'concurrent/struct'
 
 require 'concurrent/atomic/atomic_reference'
+require 'concurrent/atom'
 require 'concurrent/async'
 require 'concurrent/dataflow'
 require 'concurrent/delay'
 require 'concurrent/future'
 require 'concurrent/ivar'
+require 'concurrent/maybe'
 require 'concurrent/mvar'
 require 'concurrent/promise'
 require 'concurrent/scheduled_task'

examples/benchmark_new_futures.rb

@@ -7,7 +7,74 @@
 
 module Concurrent
 
-  # {include:file:doc/agent.md}
+  # `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. 
+  #
+  # @!macro copy_options
+  # 
+  # @example Simple Example
+  # 
+  #   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
+  # 
+  # @example With Validation and Error Handling
+  # 
+  #   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
+  # 
+  # @example With Observation
+  # 
+  #   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]
   #
   # @!attribute [r] timeout
   #   @return [Fixnum] the maximum number of seconds before an update is cancelled