concurrent-ruby 0.8.0 → 0.9.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c1cb9ee067ce09d0d58e0dbf2b704e9f05f3f23c
-  data.tar.gz: f70953ed219fd7da3f2011f426ed889e0293e65f
+  metadata.gz: 6e100cda902e2d18d80d34e38ec541d11bde399a
+  data.tar.gz: a56ad16d5a76aa677befbdf3ad2f7b47b0cc1fcb
 SHA512:
-  metadata.gz: 23d3c454c1a17957ddb8c51320ca9ea0f365e8fb2e828b5a27e2db18d42d144679047198fcdb0dc5393349cfbfa84ba801baf5474b009634739a25e8585fb8d8
-  data.tar.gz: 45ba36f7d1aaba1dd7e5fc7a10a6922a5327c8f975bd4f5cabb2162b2b76b293884688f9bb8cbcfe8b23d61bb8cd4fd7b504b80360a3c28e204935169a67d167
+  metadata.gz: 066dcc901e922bb751c79acf6249b693984cda1674adf40efc7dbdd782ca22ff8f313dd4674d282b9b22721522ab03aa481c93399fc94017cc8d90a4c17e2acf
+  data.tar.gz: 36d5fe13bebec7e07b3639c65deb455d0bbcb091a11678c05c8664213573179117517d3f2f097d6413a9f71fc09e1193b8ec189ccaa6d1c422779994638015cd

data/CHANGELOG.md

@@ -1,11 +1,106 @@
-### Next Release v0.8.0 (25 January 2015)
+### Next Release v0.9.0 (Target Date: 7 June 2015)
+
+* 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
+
+## Current 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
 
-## Current Release v0.7.2 (24 January 2015)
+### 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

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) [![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>
@@ -50,52 +50,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 is not in core?*
+
+- **Actor** - partial documentation and tests, stability good. 
+- **Future/Promise Framework** - partial documentation and tests, stability good.
+- **Agent** - incomplete behaviour compared to Clojure's model, stability good.
+- **Channel** - missing documentation, stability good.
+- **Exchanger** - known race issue.
+- **LazyRegister** - missing documentation and tests.   
 
 ## Usage
 
@@ -112,29 +151,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 +202,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,22 +240,22 @@ 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              # Build core and extension gems
+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
 
 *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
@@ -218,7 +267,7 @@ rake compile            # Compile all the extensions
 * [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,59 @@
 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)
+
 # 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

data/lib/concurrent/async.rb

@@ -8,13 +8,92 @@ require 'concurrent/executor/serialized_execution'
 
 module Concurrent
 
-  # {include:file:doc/async.md}
+  # A mixin module that provides simple asynchronous behavior to any standard
+  # class/object or object. 
+  # 
+  # ```cucumber
+  # Feature:
+  #   As a stateful, plain old Ruby class/object
+  #   I want safe, asynchronous behavior
+  #   So my long-running methods don't block the main thread
+  # ```
+  # 
+  # Stateful, mutable objects must be managed carefully when used asynchronously.
+  # But Ruby is an object-oriented language so designing with objects and classes
+  # plays to Ruby's strengths and is often more natural to many Ruby programmers.
+  # The `Async` module is a way to mix simple yet powerful asynchronous capabilities
+  # into any plain old Ruby object or class. These capabilities provide a reasonable
+  # level of thread safe guarantees when used correctly.
+  # 
+  # When this module is mixed into a class or object it provides to new methods:
+  # `async` and `await`. These methods are thread safe with respect to the enclosing
+  # object. The former method allows methods to be called asynchronously by posting
+  # to the global thread pool. The latter allows a method to be called synchronously
+  # on the current thread but does so safely with respect to any pending asynchronous
+  # method calls. Both methods return an `Obligation` which can be inspected for
+  # the result of the method call. Calling a method with `async` will return a
+  # `:pending` `Obligation` whereas `await` will return a `:complete` `Obligation`.
+  # 
+  # Very loosely based on the `async` and `await` keywords in C#.
+  # 
+  # ### An Important Note About Initialization
+  # 
+  # > This module depends on several internal stnchronization mechanisms that
+  # > must be initialized prior to calling any of the async/await/executor methods.
+  # > To ensure thread-safe initialization the class `new` method will be made
+  # > private when the `Concurrent::Async` module is included. A factory method
+  # > called `create` will be defined in its place. The `create`factory will
+  # > create a new object instance, passing all arguments to the constructor,
+  # > and will initialize all stnchronization mechanisms. This is the only way
+  # > thread-safe initialization can be guaranteed. 
+  # 
+  # ### An Important Note About Thread Safe Guarantees
+  # 
+  # > Thread safe guarantees can only be made when asynchronous method calls
+  # > are not mixed with synchronous method calls. Use only synchronous calls
+  # > when the object is used exclusively on a single thread. Use only
+  # > `async` and `await` when the object is shared between threads. Once you
+  # > call a method using `async`, you should no longer call any methods
+  # > directly on the object. Use `async` and `await` exclusively from then on.
+  # > With careful programming it is possible to switch back and forth but it's
+  # > also very easy to create race conditions and break your application.
+  # > Basically, it's "async all the way down."
+  # 
+  # @example
+  # 
+  #   class Echo
+  #     include Concurrent::Async
+  #   
+  #     def echo(msg)
+  #       sleep(rand)
+  #       print "#{msg}\n"
+  #       nil
+  #     end
+  #   end
   #
-  # @since 0.6.0
+  #   horn = Echo.new #=> NoMethodError: private method `new' called for Echo:Class
+  #   
+  #   horn = Echo.create
+  #   horn.echo('zero')      # synchronous, not thread-safe
+  #   
+  #   horn.async.echo('one') # asynchronous, non-blocking, thread-safe
+  #   horn.await.echo('two') # synchronous, blocking, thread-safe
   #
-  # @see Concurrent::Obligation
+  # @see Concurrent::Concern::Obligation
+  # @see Concurrent::IVar
   module Async
 
+    # @!method self.create(*args, &block)
+    #
+    #   The factory method used to create new instances of the asynchronous
+    #   class. Used instead of `new` to ensure proper initialization of the
+    #   synchronization mechanisms.
+    #
+    #   @param [Array<Object>] args Zero or more arguments to be passed to the
+    #     object's initializer.
+    #   @param [Proc] bloc Optional block to pass to the object's initializer.
+    #   @return [Object] A properly initialized object of the asynchronous class.
+
     # Check for the presence of a method on an object and determine if a given
     # set of arguments matches the required arity.
     #
@@ -34,7 +113,9 @@ module Concurrent
     # @see http://www.ruby-doc.org/core-2.1.1/Method.html#method-i-arity Method#arity
     # @see http://ruby-doc.org/core-2.1.0/Object.html#method-i-respond_to-3F Object#respond_to?
     # @see http://www.ruby-doc.org/core-2.1.0/BasicObject.html#method-i-method_missing BasicObject#method_missing
-    def validate_argc(obj, method, *args)
+    #
+    # @!visibility private
+    def self.validate_argc(obj, method, *args)
       argc = args.length
       arity = obj.method(method).arity
 
@@ -44,12 +125,36 @@ module Concurrent
         raise ArgumentError.new("wrong number of arguments (#{argc} for #{arity}..*)")
       end
     end
-    module_function :validate_argc
+
+    # @!visibility private
+    def self.included(base)
+      base.singleton_class.send(:alias_method, :original_new, :new)
+      base.send(:private_class_method, :original_new)
+      base.extend(ClassMethods)
+      super(base)
+    end
+
+    # @!visibility private
+    module ClassMethods
+
+      # @deprecated
+      def new(*args, &block)
+        warn '[DEPRECATED] use the `create` method instead'
+        create(*args, &block)
+      end
+
+      def create(*args, &block)
+        obj = original_new(*args, &block)
+        obj.send(:init_synchronization)
+        obj
+      end
+    end
+    private_constant :ClassMethods
 
     # Delegates asynchronous, thread-safe method calls to the wrapped object.
     #
     # @!visibility private
-    class AsyncDelegator # :nodoc:
+    class AsyncDelegator
 
       # Create a new delegator object wrapping the given delegate,
       # protecting it with the given serializer, and executing it on the
@@ -84,14 +189,11 @@ module Concurrent
         self.define_singleton_method(method) do |*args2|
           Async::validate_argc(@delegate, method, *args2)
           ivar = Concurrent::IVar.new
-          value, reason = nil, nil
           @serializer.post(@executor.value) do
             begin
-              value = @delegate.send(method, *args2, &block)
+              ivar.set(@delegate.send(method, *args2, &block))
             rescue => reason
-              # caught
-            ensure
-              ivar.complete(reason.nil?, value, reason)
+              ivar.fail(reason)
             end
           end
           ivar.value if @blocking
@@ -101,6 +203,7 @@ module Concurrent
         self.send(method, *args)
       end
     end
+    private_constant :AsyncDelegator
 
     # Causes the chained method call to be performed asynchronously on the
     # global thread pool. The method called by this method will return a
@@ -115,26 +218,24 @@ module Concurrent
     # library, some edge cases will be missed. For more information see
     # the documentation for the `validate_argc` method.
     #
-    # @note The method call is guaranteed to be thread safe  with respect to
-    #   all other method calls against the same object that are called with
-    #   either `async` or `await`. The mutable nature of Ruby references
-    #   (and object orientation in general) prevent any other thread safety
-    #   guarantees. Do NOT mix non-protected method calls with protected
-    #   method call. Use *only* protected method calls when sharing the object
-    #   between threads.
+    # @!macro [attach] async_thread_safety_warning
+    #   @note The method call is guaranteed to be thread safe with respect to
+    #     all other method calls against the same object that are called with
+    #     either `async` or `await`. The mutable nature of Ruby references
+    #     (and object orientation in general) prevent any other thread safety
+    #     guarantees. Do NOT mix non-protected method calls with protected
+    #     method call. Use *only* protected method calls when sharing the object
+    #     between threads.
     #
     # @return [Concurrent::IVar] the pending result of the asynchronous operation
     #
-    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
     # @raise [NameError] the object does not respond to `method` method
     # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @see Concurrent::IVar
     def async
-      raise InitializationError.new('#init_mutex was never called') unless @__async_initialized__
       @__async_delegator__.value
     end
-    alias_method :future, :async
 
     # Causes the chained method call to be performed synchronously on the
     # current thread. The method called by this method will return an
@@ -149,58 +250,71 @@ module Concurrent
     # library, some edge cases will be missed. For more information see
     # the documentation for the `validate_argc` method.
     #
-    # @note The method call is guaranteed to be thread safe  with respect to
-    #   all other method calls against the same object that are called with
-    #   either `async` or `await`. The mutable nature of Ruby references
-    #   (and object orientation in general) prevent any other thread safety
-    #   guarantees. Do NOT mix non-protected method calls with protected
-    #   method call. Use *only* protected method calls when sharing the object
-    #   between threads.
+    # @!macro async_thread_safety_warning
     #
     # @return [Concurrent::IVar] the completed result of the synchronous operation
     #
-    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
     # @raise [NameError] the object does not respond to `method` method
     # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @see Concurrent::IVar
     def await
-      raise InitializationError.new('#init_mutex was never called') unless @__async_initialized__
       @__await_delegator__.value
     end
-    alias_method :delay, :await
 
-    # Set a new executor
+    # Set a new executor.
     #
-    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
-    # @raise [ArgumentError] executor has already been set
+    # @raise [ArgumentError] executor has already been set.
     def executor=(executor)
-      raise InitializationError.new('#init_mutex was never called') unless @__async_initialized__
       @__async_executor__.reconfigure { executor } or
         raise ArgumentError.new('executor has already been set')
     end
 
-    # Initialize the internal serializer and other synchronization objects. This method
-    # *must* be called from the constructor of the including class or explicitly
-    # by the caller prior to calling any other methods. If `init_mutex` is *not*
-    # called explicitly the async/await/executor methods will raize a
-    # `Concurrent::InitializationError`. This is the only way thread-safe
-    # initialization can be guaranteed.
+    # Initialize the internal serializer and other stnchronization mechanisms.
     #
-    # @note This method *must* be called from the constructor of the including
-    #       class or explicitly by the caller prior to calling any other methods.
-    #       This is the only way thread-safe initialization can be guaranteed.
+    # @note This method *must* be called immediately upon object construction.
+    #   This is the only way thread-safe initialization can be guaranteed.
     #
     # @raise [Concurrent::InitializationError] when called more than once
+    #
+    # @!visibility private
+    # @deprecated
     def init_mutex
-      raise InitializationError.new('#init_mutex was already called') if @__async_initialized__
+      warn '[DEPRECATED] use the `create` method instead'
+      init_synchronization
+    rescue InitializationError
+      # suppress
+    end
+
+    private
+
+    # Initialize the internal serializer and other stnchronization mechanisms.
+    #
+    # @note This method *must* be called immediately upon object construction.
+    #   This is the only way thread-safe initialization can be guaranteed.
+    #
+    # @raise [Concurrent::InitializationError] when called more than once
+    #
+    # @!visibility private
+    def init_synchronization
+      return self if @__async_initialized__
+
       @__async_initialized__ = true
       serializer = Concurrent::SerializedExecution.new
-      @__async_executor__ = Delay.new{ Concurrent.configuration.global_operation_pool }
-      @__await_delegator__ = Delay.new{ AsyncDelegator.new(
-        self, Delay.new{ Concurrent::ImmediateExecutor.new }, serializer, true) }
-      @__async_delegator__ = Delay.new{ AsyncDelegator.new(
-        self, @__async_executor__, serializer, false) }
+
+      @__async_executor__ = Delay.new {
+        Concurrent.global_io_executor
+      }
+
+      @__await_delegator__ = Delay.new {
+        AsyncDelegator.new(self, Delay.new{ Concurrent::ImmediateExecutor.new }, serializer, true)
+      }
+
+      @__async_delegator__ = Delay.new {
+        AsyncDelegator.new(self, @__async_executor__, serializer, false)
+      }
+
+      self
     end
   end
 end