concurrent-ruby 0.8.0.pre2-java → 0.9.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f05e002bf687416f80b224ae58618eaaabd55cda
-  data.tar.gz: 0189afd2a533af45e9809e870810996c9fb77f8f
+  metadata.gz: 94cc8d875af4081f3b01de2517796f79c43d4627
+  data.tar.gz: d07bab5b8c928d783d684604c7af23940cd87f7b
 SHA512:
-  metadata.gz: d00c87168dff492aeb6503c648f745a95d5b1ac5cd4b27872d9c437a3fc0b5dc8d96ae2109a42ac2253dc8655d6f20516028025e5447b117d72cb7bc0c7ce656
-  data.tar.gz: 129a31e92dae0d916399fbf81f90bee31d5d57a7ca3e71e48aef34f704b231c5c07e339c6862e89aa0e5b2c55dcfcdfa7a80fecd15ec8b9c2c0da3715ee200ba
+  metadata.gz: 3c446e8f8dbd430177b94ff9a8652665bcd1bc13e8d3aad5194ac16cdf19ab83c9f26de49b3036fa2bff4ccc9f4adc6e2bdb75187b59a039d45109a0f5c880d9
+  data.tar.gz: 798f45059166050420b8b9e143615e0fce2b97f2c5a8a281e5953b86f97846bfd31b39f5b9602c45a17c34799bec0fad422d738a962d73bb42fa3cf0926df65e

data/CHANGELOG.md

@@ -1,4 +1,110 @@
-### Next Release v0.7.2 (TBD)
+## Current Release v0.9.0 (10 July 2015)
+
+* Updated `AtomicReference`
+  - `AtomicReference#try_update` now simply returns instead of raising exception
+  - `AtomicReference#try_update!` was added to raise exceptions if an update
+    fails. Note: this is the same behavior as the old `try_update`
+* Pure Java implementations of
+  - `AtomicBoolean`
+  - `AtomicFixnum`
+  - `Semaphore`
+* Fixed bug when pruning Ruby thread pools
+* Fixed bug in time calculations within `ScheduledTask`
+* Default `count` in `CountDownLatch` to 1
+* Use monotonic clock for all timers via `Concurrent.monotonic_time`
+  - Use `Process.clock_gettime(Process::CLOCK_MONOTONIC)` when available
+  - Fallback to `java.lang.System.nanoTime()` on unsupported JRuby versions
+  - Pure Ruby implementation for everything else
+  - Effects `Concurrent.timer`, `Concurrent.timeout`, `TimerSet`, `TimerTask`, and `ScheduledTask`
+* Deprecated all clock-time based timer scheduling
+  - Only support scheduling by delay
+  - Effects `Concurrent.timer`, `TimerSet`, and `ScheduledTask`
+* Added new `ReadWriteLock` class
+* Consistent `at_exit` behavior for Java and Ruby thread pools.
+* Added `at_exit` handler to Ruby thread pools (already in Java thread pools)
+  - Ruby handler stores the object id and retrieves from `ObjectSpace`
+  - JRuby disables `ObjectSpace` by default so that handler stores the object reference
+* Added a `:stop_on_exit` option to thread pools to enable/disable `at_exit` handler
+* Updated thread pool docs to better explain shutting down thread pools
+* Simpler `:executor` option syntax for all abstractions which support this option
+* Added `Executor#auto_terminate?` predicate method (for thread pools)
+* Added `at_exit` handler to `TimerSet`
+* Simplified auto-termination of the global executors
+  - Can now disable auto-termination of global executors
+  - Added shutdown/kill/wait_for_termination variants for global executors
+* Can now disable auto-termination for *all* executors (the nuclear option)
+* Simplified auto-termination of the global executors
+* Deprecated terms "task pool" and "operation pool"
+  - New terms are "io executor" and "fast executor"
+  - New functions added with new names
+  - Deprecation warnings added to functions referencing old names
+* Moved all thread pool related functions from `Concurrent::Configuration` to `Concurrent`
+  - Old functions still exist with deprecation warnings
+  - New functions have updated names as appropriate
+* All high-level abstractions default to the "io executor"
+* Fixed bug in `Actor` causing it to prematurely warm global thread pools on gem load
+  - This also fixed a `RejectedExecutionError` bug when running with minitest/autorun via JRuby
+* Moved global logger up to the `Concurrent` namespace and refactored the code
+* Optimized the performance of `Delay`
+  - Fixed a bug in which no executor option on construction caused block execution on a global thread pool
+* Numerous improvements and bug fixes to `TimerSet`
+* Fixed deadlock of `Future` when the handler raises Exception
+* Added shared specs for more classes
+* New concurrency abstractions including:
+  - `Atom`
+  - `Maybe`
+  - `ImmutableStruct`
+  - `MutableStruct`
+  - `SettableStruct`
+* Created an Edge gem for unstable abstractions including
+  - `Actor`
+  - `Agent`
+  - `Channel`
+  - `Exchanger`
+  - `LazyRegister`
+  - **new Future Framework** <http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge.html> - unified
+    implementation of Futures and Promises which combines Features of previous `Future`,
+    `Promise`, `IVar`, `Event`, `Probe`, `dataflow`, `Delay`, `TimerTask` into single framework. It uses extensively
+    new synchronization layer to make all the paths **lock-free** with exception of blocking threads on `#wait`.
+    It offers better performance and does not block threads when not required.
+* Actor framework changes:
+  - fixed reset loop in Pool
+  - Pool can use any actor as a worker, abstract worker class is no longer needed.
+  - Actor events not have format `[:event_name, *payload]` instead of just the Symbol.
+  - Actor now uses new Future/Promise Framework instead of `IVar` for better interoperability
+  - Behaviour definition array was simplified to `[BehaviourClass1, [BehaviourClass2, *initialization_args]]`
+  - Linking behavior responds to :linked message by returning array of linked actors
+  - Supervised behavior is removed in favour of just Linking
+  - RestartingContext is supervised by default now, `supervise: true` is not required any more
+  - Events can be private and public, so far only difference is that Linking will
+    pass to linked actors only public messages. Adding private :restarting and
+    :resetting events which are send before the actor restarts or resets allowing
+    to add callbacks to cleanup current child actors.
+  - Print also object_id in Reference to_s
+  - Add AbstractContext#default_executor to be able to override executor class wide
+  - Add basic IO example
+  - Documentation somewhat improved
+  - All messages should have same priority. It's now possible to send `actor << job1 << job2 << :terminate!` and
+    be sure that both jobs are processed first.
+* Refactored `Channel` to use newer synchronization objects
+* Added `#reset` and `#cancel` methods to `TimerSet`
+* Added `#cancel` method to `Future` and `ScheduledTask`
+* Refactored `TimerSet` to use `ScheduledTask`
+* Updated `Async` with a factory that initializes the object
+* Deprecated `Concurrent.timer` and `Concurrent.timeout`
+* Reduced max threads on pure-Ruby thread pools (abends around 14751 threads)
+* Moved many private/internal classes/modules into "namespace" modules
+* Removed brute-force killing of threads in tests
+* Fixed a thread pool bug when the operating system cannot allocate more threads
+
+### Release v0.8.0 (25 January 2015)
+
+* C extension for MRI have been extracted into the `concurrent-ruby-ext` companion gem.
+  Please see the README for more detail.
+* Better variable isolation in `Promise` and `Future` via an `:args` option
+* Continued to update intermittently failing tests
+
+### Release v0.7.2 (24 January 2015)
 
 * 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
@@ -6,11 +112,16 @@
 * 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
+* Fixed minor `require` bug in `ThreadLocalVar` class
+* Fixed race condition bug in `TimerSet` class
+* Fixed race condition bug in `TimerSet` class
+* Fixed signal bug in `TimerSet#post` method
 * 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
+* Multiple documentation updates
 
-## Current Release v0.7.1 (4 December 2014)
+### 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.
 
@@ -55,7 +166,7 @@ Please see the [roadmap](https://github.com/ruby-concurrency/concurrent-ruby/iss
   - `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 
+* 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)`

data/README.md

@@ -1,5 +1,5 @@
 # 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)
+[![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) [![Build status](https://ci.appveyor.com/api/projects/status/iq8aboyuu3etad4w?svg=true)](https://ci.appveyor.com/project/rubyconcurrency/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>
@@ -39,6 +39,7 @@
 
 MRI 1.9.3, 2.0, 2.1, 2.2, JRuby (1.9 mode), and Rubinius 2.x are supported.
 This gem should be fully compatible with any interpreter that is compliant with Ruby 1.9.3 or newer.
+Java 8 is required for JRuby (Java 7 support is deprecated in version 0.9 and will be removed in 1.0).
 
 ## Features & Documentation
 
@@ -50,52 +51,91 @@ 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
+#### General-purpose 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.
+* [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/Dataflow.html): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
+  * [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.
 * [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. 
-* [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Channel.html): Communicating Sequential Processes (CSP). 
 
-### Java-inspired ThreadPools and other executors
+#### Thread-safe Value Objects
 
-* See [ThreadPool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
+* `Maybe` A thread-safe, immutable object representing an optional value, based on
+  [Haskell Data.Maybe](https://hackage.haskell.org/package/base-4.2.0.1/docs/Data-Maybe.html).
+* `Delay` Lazy evaluation of a block yielding an immutable result. Based on Clojure's
+   [delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.html).
 
-### Thread-safe Observers
+#### Thread-safe Structures
 
-* [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)
+Derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html):
 
-### Thread synchronization classes and algorithms
+* `ImmutableStruct` Immutable struct where values are set at construction and cannot be changed later.
+* `MutableStruct` Synchronized, mutable struct where values can be safely changed at any time.
+* `SettableStruct` Synchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.
 
-Lower-level abstractions mainly used as building blocks. 
+#### Java-inspired ThreadPools and Other Executors
 
-* [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)
+* 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 variables
+#### Thread Synchronization Classes and Algorithms
 
-Lower-level abstractions mainly used as building blocks. 
+* [CountdownLatch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html)
+* [CyclicBarrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html)
+* [Event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html)
+* [Semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html)
+
+#### Thread-safe Variables
 
 * [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)
+* [AtomicReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutexAtomic.html)
 * [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)
+* [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)
+* [ReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReadWriteLock.html)
+
+### Edge Features
+
+These are available in the `concurrent-ruby-edge` companion gem, installed with `gem install concurrent-ruby-edge`.
+
+These features are under active development and may change frequently. They are expected not to
+keep backward compatibility (there may also lack tests and documentation). Semantic versions will
+be obeyed though. Features developed in `concurrent-ruby-edge` are expected to move to `concurrent-ruby` when final.
+
+* [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html):
+  Implements the Actor Model, where concurrent actors exchange messages.
+* [new Future Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge.html) - new 
+  unified implementation of Futures and Promises which combines Features of previous `Future`,
+  `Promise`, `IVar`, `Event`, `Probe`, `dataflow`, `Delay`, `TimerTask` into single framework. It uses extensively
+  new synchronization layer to make all the paths **lock-free** with exception of blocking threads on `#wait`.
+  It offers better performance and does not block threads when not required.
+* [Agent](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Agent.html): A single atomic value that represents an identity.
+* [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Channel.html):
+  Communicating Sequential Processes (CSP).
+* [Exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html)
+* [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
+* [New Future Promise Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge.html) - new 
+  unified implementation of Futures and Promises which combines Features of previous `Future`,
+  `Promise`, `IVar`, `Probe`, `dataflow`, `Delay`, `TimerTask` into single framework. It uses extensively
+  new synchronization layer to make all the paths lock-free with exception of blocking threads on `#wait`.
+  It offers better performance and does not block threads (exception being `#wait` and similar methods where it's
+  intended).
+
+
+#### Statuses:
+
+*Why are these not in core?*
+
+- **Actor** - Partial documentation and tests; stability is good. 
+- **Future/Promise Framework** - API changes; partial documentation and tests; stability good.
+- **Agent** - Incomplete behaviour compared to Clojure's models; stability good.
+- **Channel** - Missing documentation; limted features; stability good.
+- **Exchanger** - Known race condition requiring a new implementation.
+- **LazyRegister** - Missing documentation and tests.   
 
 ## Usage
 
@@ -112,29 +152,39 @@ require 'concurrent'                # everything
 
 # groups
 
-require 'concurrent/actor'          # Concurrent::Actor and supporting code
 require 'concurrent/atomics'        # atomic and thread synchronization classes
-require 'concurrent/channels'       # Concurrent::Channel and supporting code
 require 'concurrent/executors'      # Thread pools and other executors
-require 'concurrent/utilities'      # utility methods such as processor count and timers
 
 # individual abstractions
 
+require 'concurrent/async'            # Concurrent::Async
+require 'concurrent/atom'             # Concurrent::Atom
+require 'concurrent/dataflow'         # Concurrent::dataflow
+require 'concurrent/delay'            # Concurrent::Delay
+require 'concurrent/future'           # Concurrent::Future
+require 'concurrent/immutable_struct' # Concurrent::ImmutableStruct
+require 'concurrent/ivar'             # Concurrent::IVar
+require 'concurrent/maybe'            # Concurrent::Maybe
+require 'concurrent/mutable_struct'   # Concurrent::MutableStruct
+require 'concurrent/mvar'             # Concurrent::MVar
+require 'concurrent/promise'          # Concurrent::Promise
+require 'concurrent/scheduled_task'   # Concurrent::ScheduledTask
+require 'concurrent/settable_struct'  # Concurrent::SettableStruct
+require 'concurrent/timer_task'       # Concurrent::TimerTask
+require 'concurrent/tvar'             # Concurrent::TVar
+
+# experimental - available in `concurrent-ruby-edge` companion gem
+
+require 'concurrent/actor'          # Concurrent::Actor and supporting code
+require 'concurrent/edge/future'    # new Future Framework
 require 'concurrent/agent'          # Concurrent::Agent
-require 'concurrent/async'          # Concurrent::Async
-require 'concurrent/atomic'         # Concurrent::Atomic (formerly the `atomic` gem)
-require 'concurrent/dataflow'       # Concurrent::dataflow
-require 'concurrent/delay'          # Concurrent::Delay
+require 'concurrent/channel '       # Concurrent::Channel and supporting code
 require 'concurrent/exchanger'      # Concurrent::Exchanger
-require 'concurrent/future'         # Concurrent::Future
-require 'concurrent/ivar'           # Concurrent::IVar
-require 'concurrent/mvar'           # Concurrent::MVar
-require 'concurrent/promise'        # Concurrent::Promise
-require 'concurrent/scheduled_task' # Concurrent::ScheduledTask
-require 'concurrent/timer_task'     # Concurrent::TimerTask
-require 'concurrent/tvar'           # Concurrent::TVar
+require 'concurrent/lazy_register'  # Concurrent::LazyRegister
 ```
 
+If the library does not behave as expected, `Concurrent.use_stdlib_logger(Logger::DEBUG)` could help to reveal the problem.
+
 ## Installation
 
 ```shell
@@ -153,8 +203,8 @@ and run `bundle install` from your shell.
 
 Potential performance improvements may be achieved under MRI by installing optional C extensions.
 To minimize installation errors the C extensions are available in the `concurrent-ruby-ext` extension
-gem. The extension gem lists `concurrent-ruby` as a dependency so it is not necessary to install both.
-Simply install the extension gen:
+gem. `concurrent-ruby` and `concurrent-ruby-ext` are always released together with same version.
+Simply install the extension gem too:
 
 ```ruby
 gem install concurrent-ruby-ext
@@ -191,34 +241,40 @@ any platform. *Documentation is forthcoming...*
 
 ```
 *MRI only*
-rake build:native       # Build concurrent-ruby-ext-<version>-<platform>.gem into the pkg directory
-rake compile:extension  # Compile extension
+bundle exec rake build:native       # Build concurrent-ruby-ext-<version>-<platform>.gem into the pkg dir
+bundle exec rake compile:extension  # Compile extension
 
 *JRuby only*
-rake build              # Build JRuby-specific core gem (alias for `build:core`)
-rake build:core         # Build concurrent-ruby-<version>-java.gem into the pkg directory
+bundle exec rake build              # Build JRuby-specific core gem (alias for `build:core`)
+bundle exec rake build:core         # Build concurrent-ruby-<version>-java.gem into the pkg directory
 
 *All except JRuby*
-rake build              # Build core and extension gems
-rake build:core         # Build concurrent-ruby-<version>.gem into the pkg directory
-rake build:ext          # Build concurrent-ruby-ext-<version>.gem into the pkg directory
+bundle exec rake build:core         # Build concurrent-ruby-<version>.gem into the pkg directory
+bundle exec rake build:ext          # Build concurrent-ruby-ext-<version>.gem into the pkg directory
+
+*When Docker IS installed*
+bundle exec rake build:windows      # Build the windows binary <version> gems per rake-compiler-dock
+bundle exec rake build              # Build core, extension, and edge gems, including Windows binaries
+
+*When Docker is NOT installed*
+bundle exec rake build              # Build core, extension, and edge gems (excluding Windows binaries)
 
 *All*
-rake clean              # Remove any temporary products
-rake clobber            # Remove any generated file
-rake compile            # Compile all the extensions
+bundle exec rake clean              # Remove any temporary products
+bundle exec rake clobber            # Remove any generated file
+bundle exec rake compile            # Compile all the extensions
 ```
 
 ## Maintainers
 
-* [Jerry D'Antonio](https://github.com/jdantonio)
+* [Jerry D'Antonio](https://github.com/jdantonio) (creator)
 * [Michele Della Torre](https://github.com/mighe)
 * [Chris Seaton](https://github.com/chrisseaton)
 * [Lucas Allan](https://github.com/lucasallan)
 * [Petr Chalupa](https://github.com/pitr-ch)
 * [Paweł Obrok](https://github.com/obrok)
 
-### Contributing
+## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/lib/concurrent.rb

@@ -1,39 +1,115 @@
 require 'concurrent/version'
 
+require 'concurrent/synchronization'
+
 require 'concurrent/configuration'
 
 require 'concurrent/atomics'
-require 'concurrent/channels'
-require 'concurrent/collections'
+require 'concurrent/errors'
 require 'concurrent/executors'
 require 'concurrent/utilities'
 
-require 'concurrent/actor'
-require 'concurrent/atomic'
-require 'concurrent/lazy_register'
-require 'concurrent/agent'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/atom'
 require 'concurrent/async'
 require 'concurrent/dataflow'
 require 'concurrent/delay'
-require 'concurrent/dereferenceable'
-require 'concurrent/errors'
-require 'concurrent/exchanger'
 require 'concurrent/future'
+require 'concurrent/immutable_struct'
 require 'concurrent/ivar'
+require 'concurrent/maybe'
+require 'concurrent/mutable_struct'
 require 'concurrent/mvar'
-require 'concurrent/obligation'
-require 'concurrent/observable'
-require 'concurrent/options_parser'
 require 'concurrent/promise'
 require 'concurrent/scheduled_task'
+require 'concurrent/settable_struct'
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
 
+# @!macro [new] internal_implementation_note
+#
+#   @note **Private Implementation:** This abstraction is a private, internal
+#     implementation detail. It should never be used directly.
+
+# @!macro [new] monotonic_clock_warning
+#
+#   @note Time calculations one all platforms and languages are sensitive to
+#     changes to the system clock. To alleviate the potential problems
+#     associated with changing the system clock while an application is running,
+#     most modern operating systems provide a monotonic clock that operates
+#     independently of the system clock. A monotonic clock cannot be used to
+#     determine human-friendly clock times. A monotonic clock is used exclusively
+#     for calculating time intervals. Not all Ruby platforms provide access to an
+#     operating system monotonic clock. On these platforms a pure-Ruby monotonic
+#     clock will be used as a fallback. An operating system monotonic clock is both
+#     faster and more reliable than the pure-Ruby implementation. The pure-Ruby
+#     implementation should be fast and reliable enough for most non-realtime
+#     operations. At this time the common Ruby platforms that provide access to an
+#     operating system monotonic clock are MRI 2.1 and above and JRuby (all versions).
+#
+#   @see http://linux.die.net/man/3/clock_gettime Linux clock_gettime(3)
+
+# @!macro [new] copy_options
+#
+#   ## Copy Options
+#
+#   Object references in Ruby are mutable. This can lead to serious
+#   problems when the {#value} of an object is a mutable reference. Which
+#   is always the case unless the value is a `Fixnum`, `Symbol`, or similar
+#   "primative" data type. Each 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 oject
+#   instance is created:
+#
+#   * `:dup_on_deref` When true the object will call the `#dup` method on
+#     the `value` object every time the `#value` methid is called
+#     (default: false)
+#   * `:freeze_on_deref` When true the object 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 argument 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)
+#
+#   When multiple deref options are set the order of operations is strictly defined.
+#   The order of deref operations is:
+#   * `:copy_on_deref`
+#   * `:dup_on_deref`
+#   * `:freeze_on_deref`
+#
+#   Because of this ordering there is no need to `#freeze` an object created by a
+#   provided `:copy_on_deref` block. Simply set `:freeze_on_deref` to `true`.
+#   Setting both `:dup_on_deref` to `true` and `:freeze_on_deref` to `true` is
+#   as close to the behavior of a "pure" functional language (like Erlang, Clojure,
+#   or Haskell) as we are likely to get in Ruby.
+
+# @!macro [attach] deref_options
+#
+#   @option opts [Boolean] :dup_on_deref (false) Call `#dup` before
+#     returning the data from {#value}
+#   @option opts [Boolean] :freeze_on_deref (false) Call `#freeze` before
+#     returning the data from {#value}
+#   @option opts [Proc] :copy_on_deref (nil) When calling the {#value}
+#     method, call the given proc passing the internal value as the sole
+#     argument then return the new value returned from the proc.
+
+# @!macro [attach] executor_and_deref_options
+#
+#   @param [Hash] opts the options used to define the behavior at update and deref
+#     and to specify the executor on which to perform actions
+#   @option opts [Executor] :executor when set use the given `Executor` instance.
+#     Three special values are also supported: `:task` returns the global task pool,
+#     `:operation` returns the global operation pool, and `:immediate` returns a new
+#     `ImmediateExecutor` object.
+#   @!macro deref_options
+
 # Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
 # F#, C#, Java, and classic concurrency patterns.
-# 
+#
 # 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