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

* upstream/master: (52 commits)
  Add test to verify that TimerSet#post returns true
  ...

Author: pitr-ch

.travis.yml

@@ -1,4 +1,5 @@
 language: ruby
+
 rvm:
   - 2.1.2
   - 2.0.0
@@ -7,15 +8,20 @@ rvm:
   - jruby-19mode
   - jruby-head
   - rbx-2
+
 jdk:
   - oraclejdk8
+
+sudo: false
+
 branches:
   only:
     - master
+
 matrix:
   allow_failures:
-    - rvm: rbx-2
     - rvm: ruby-head
     - rvm: jruby-head
     - rvm: 1.9.3
+
 script: "bundle exec rake compile && bundle exec rspec --color --backtrace --tag ~unfinished --seed 1 --format documentation ./spec"

.yardopts

@@ -10,5 +10,6 @@
 ./lib/**/*.rb
 ./ext/concurrent_ruby_ext/**/*.c
 -
+doc/thread_pools.md
 README.md
 LICENSE.txt

CHANGELOG.md

@@ -1,4 +1,16 @@
-### Upcoming Release v0.7.1 (TBD)
+### Next Release v0.7.2 (TBD)
+
+* New `Semaphore` class based on [java.util.concurrent.Semaphore](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Semaphore.html)
+* New `Promise.all?` and `Promise.any?` class methods
+* Renamed `:overflow_policy` on thread pools to `:fallback_policy`
+* Thread pools still accept the `:overflow_policy` option but display a warning
+* Thread pools now implement `fallback_policy` behavior when not running (rather than universally rejecting tasks)
+* Fixed minor `set_deref_options` constructor bug in `Promise` class
+* Numerous non-functional updates to clear warning when running in debug mode
+* Fixed more intermittently failing tests
+* Tests now run on new Travis build environment
+
+## Current Release v0.7.1 (4 December 2014)
 
 Please see the [roadmap](https://github.com/ruby-concurrency/concurrent-ruby/issues/142) for more information on the next planned release.
 
@@ -14,10 +26,12 @@ Please see the [roadmap](https://github.com/ruby-concurrency/concurrent-ruby/iss
 * Prevent `Actor` from using an `ImmediateExecutor` (causes deadlock)
 * Added missing synchronizations to `TimerSet`
 * Fixed bug with return value of `Concurrent::Actor::Utils::Pool#ask`
+* Fixed timing bug in `TimerTask`
+* Fixed bug when creating a `JavaThreadPoolExecutor` with minimum pool size of zero
 * Removed confusing warning when not using native extenstions
 * Improved documentation
 
-## Current Release v0.7.0 (13 August 2014)
+### Release v0.7.0 (13 August 2014)
 
 * Merge the [atomic](https://github.com/ruby-concurrency/atomic) gem
   - Pure Ruby `MutexAtomic` atomic reference class

README.md

@@ -35,115 +35,68 @@
   </tr>
 </table>
 
-## Features & Documentation
-
-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
-  [Agent](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Agent.html),
-  [Async](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Async.html),
-  [Future](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Future.html),
-  [Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html),
-  [ScheduledTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ScheduledTask.html),
-  and [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html) 
-* Fast, light-weight [Actor model](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html) implementation. 
-* Thread-safe variables including
-  [I-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/IVar.html),
-  [M-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MVar.html),
-  [thread-local variables](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html),
-  and [software transactional memory](https://github.com/ruby-concurrency/concurrent-ruby/wiki/TVar-(STM))
-* Thread synchronization classes and algorithms including
-  [condition](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Condition.html),
-  [countdown latch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html),
-  [dataflow](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Dataflow), 
-  [event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html),
-  [exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html),
-  and [timeout](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timeout-class_method)
-* Java-inspired [executors](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Thread%20Pools) (thread pools and more)
-* [And many more](http://ruby-concurrency.github.io/concurrent-ruby/index.html)...
-
-### Semantic Versioning
-
-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.
+MRI 1.9.3, 2.0, 2.1, JRuby (1.9 mode), and Rubinius 2.x are supported.
 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
-
-Many more code examples can be found in the documentation for each class (linked above).
-
-Future and ScheduledTask:
-
-```ruby    
-require 'concurrent'
-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
-
-# 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
-
-# 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
-```
+## Features & Documentation
 
-Actor:
+We have a roadmap guiding our work toward the [v1.0.0 release](https://github.com/ruby-concurrency/concurrent-ruby/wiki/v1.0-Roadmap).
 
-```ruby
-class Counter < Concurrent::Actor::Context
-  # Include context of an actor which gives this class access to reference
-  # and other information about the actor
-
-  # use initialize as you wish
-  def initialize(initial_value)
-    @count = initial_value
-  end
-
-  # override on_message to define actor's behaviour
-  def on_message(message)
-    if Integer === message
-      @count += message
-    end
-  end
-end #
-
-# Create new actor naming the instance 'first'.
-# Return value is a reference to the actor, the actual actor is never returned.
-counter = Counter.spawn(:first, 5)
-
-# Tell a message and forget returning self.
-counter.tell(1)
-counter << 1
-# (First counter now contains 7.)
-
-# Send a messages asking for a result.
-counter.ask(0).class
-counter.ask(0).value
-```
+The primary site for documentation is the automatically generated [API documentation](http://ruby-concurrency.github.io/concurrent-ruby/frames.html)
+
+We also have a [mailing list](http://groups.google.com/group/concurrent-ruby).
+
+This library contains a variety of concurrency abstractions at high and low levels. One of the high-level abstractions is likely to meet most common needs. 
+
+### High-level, general-purpose asynchronous concurrency abstractions
+
+* [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html): Implements the Actor Model, where concurrent actors exchange messages.
+* [Agent](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Agent.html): A single atomic value that represents an identity.
+* [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.
+* [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/Dataflow.html): 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.
+* [ScheduledTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ScheduledTask.html): Like a Future scheduled for a specific future time.
+* [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html): A Thread that periodically wakes up to perform work at regular intervals. 
+
+### Java-inspired ThreadPools and other executors
+
+* See [ThreadPool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
+
+### Thread-safe Observers
+
+* [Concurrent::Observable](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Observable.html) mixin module
+* [CopyOnNotifyObserverSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CopyOnNotifyObserverSet.html)
+* [CopyOnWriteObserverSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CopyOnWriteObserverSet.html)
+
+### Thread synchronization classes and algorithms
+
+Lower-level abstractions mainly used as building blocks. 
+
+* [condition](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Condition.html)
+* [countdown latch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html)
+* [cyclic barrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html)
+* [event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html)
+* [exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html)
+* [semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html)
+* [timeout](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timeout-class_method)
+* [timer](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timer-class_method)
+
+### Thread-safe variables
+
+Lower-level abstractions mainly used as building blocks. 
+
+* [AtomicBoolean](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicBoolean.html)
+* [AtomicFixnum](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicFixnum.html)
+* AtomicReference (no docs currently available, check source)
+* [I-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/IVar.html) (IVar)
+* [M-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MVar.html) (MVar)
+* [thread-local variables](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html)
+* [software transactional memory](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) (TVar)
 
 ## Installing and Building
 

doc/actor/main.md

@@ -29,6 +29,40 @@ Concurrency is hard to get right, actors are one of many ways how to simplify th
 
 ## Quick example
 
+An example:
+
+```ruby
+class Counter < Concurrent::Actor::Context
+  # Include context of an actor which gives this class access to reference
+  # and other information about the actor
+
+  # use initialize as you wish
+  def initialize(initial_value)
+    @count = initial_value
+  end
+
+  # override on_message to define actor's behaviour
+  def on_message(message)
+    if Integer === message
+      @count += message
+    end
+  end
+end #
+
+# Create new actor naming the instance 'first'.
+# Return value is a reference to the actor, the actual actor is never returned.
+counter = Counter.spawn(:first, 5)
+
+# Tell a message and forget returning self.
+counter.tell(1)
+counter << 1
+# (First counter now contains 7.)
+
+# Send a messages asking for a result.
+counter.ask(0).class
+counter.ask(0).value
+```
+
 {include:file:doc/actor/quick.out.rb}
 
 ## Spawning actors

doc/future.md

@@ -19,23 +19,35 @@ The `Future` class also includes the behavior of the Ruby standard library [Obse
 
 A fulfilled example:
 
-```ruby
+```ruby    
 require 'concurrent'
+require 'thread'   # for Queue
+require 'open-uri' # for open(uri)
 
-count = Concurrent::Future.new{ sleep(10); 10 }.execute
-count.state #=> :pending
-count.pending? #=> true
+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
 
-# do stuff...
+# Future
+price = Concurrent::Future.execute{ Ticker.new.get_year_end_closing('TWTR', 2013) }
+price.state #=> :pending
+price.pending? #=> true
+price.value(0) #=> nil (does not block)
 
-count.value(0) #=> nil (does not block)
+sleep(1)    # do other stuff
 
-count.value #=> 10 (after blocking)
-count.state #=> :fulfilled
-count.fulfilled? #=> true
-count.value #=> 10
+price.value #=> 63.65 (after blocking if neccesary)
+price.state #=> :fulfilled
+price.fulfilled? #=> true
+price.value #=> 63.65
 ```
 
+
+
 A rejected example:
 
 ```ruby
@@ -48,6 +60,10 @@ count.rejected? #=> true
 count.reason #=> #<StandardError: Boom!> 
 ```
 
+
+
+
+
 An example with observation:
 
 ```ruby