concurrent-ruby 0.9.2-java → 1.0.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58fcb6fe96e8a611c32e4d23d3016f11786496f7
-  data.tar.gz: bed6902157997d4f55097c9bf4829e3e75a38622
+  metadata.gz: 495623f62c0b2d65273bf9bbd7ed0d27b0a0f25e
+  data.tar.gz: bcb17e5681ab7d8b718ec7baa49fe69d2796ac87
 SHA512:
-  metadata.gz: 83c7e538c3bafbd71ae156d393110ab3387dd83b56a0d6a1f06588da2e430e41bd3896f1d50f1d3b047c3523a7f4985d4a72a60e6bf54d1bc011fadc9c3a7ce2
-  data.tar.gz: f589e034b4bc9138b9c44c2f76ffeaccef3d01299e93ede9866f6f972b4aa3153b4f56fa8b8aa076b5084cecaff858423d8f1bb712dc117f4c38b481e5af59b3
+  metadata.gz: ba74c5a7a368e70a8b5fa5238a0bdc0d0d13825bc6e6c3d38b6ce64c8a1558f526812148cc823f26e563b1bcc02ae6d4a58f4bb717498b77db65876698e0e9dd
+  data.tar.gz: 39ca74c4ff022cb1c1b306e418b9e56bbb4df31b258d64b6793ad99a18b8b71fe13b0f6862b6153331b2ed8c84e86284d52a37de0bcdd137a4f21c20551bef5d

data/CHANGELOG.md

@@ -1,4 +1,52 @@
-## Current Release v0.9.1 (09 August 2015)
+## Current Release v1.0.0 (13 November 2015)
+
+* Rename `attr_volatile_with_cas` to `attr_atomic`
+* Add `clear_each` to `LockFreeStack`
+* Update `AtomicReference` documentation
+* Further updates and improvements to the synchronization layer.
+* Performance and memory usage performance with `Actor` logging.
+* Fixed `ThreadPoolExecutor` task count methods.
+* Improved `Async` performance for both short and long-lived objects.
+* Fixed bug in `LockFreeLinkedSet`.
+* Fixed bug in which `Agent#await` triggered a validation failure.
+* Further `Channel` updates.
+* Adopted a project Code of Conduct
+* Cleared interpreter warnings
+* Fixed bug in `ThreadPoolExecutor` task count methods
+* Fixed bug in 'LockFreeLinkedSet'
+* Improved Java extension loading
+* Handle Exception children in Edge::Future
+* Continued improvements to channel
+* Removed interpreter warnings.
+* Shared constants now in `lib/concurrent/constants.rb`
+* Refactored many tests.
+* Improved synchronization layer/memory model documentation.
+* Bug fix in Edge `Future#flat`
+* Brand new `Channel` implementation in Edge gem.
+* Simplification of `RubySingleThreadExecutor`
+* `Async` improvements
+  - Each object uses its own `SingleThreadExecutor` instead of the global thread pool.
+  - No longers supports executor injection
+  - Much better documentation
+* `Atom` updates
+  - No longer `Dereferenceable`
+  - Now `Observable`
+  - Added a `#reset` method
+* Brand new `Agent` API and implementation. Now functionally equivalent to Clojure.
+* Continued improvements to the synchronization layer
+* Merged in the `thread_safe` gem
+  - `Concurrent::Array`
+  - `Concurrent::Hash`
+  - `Concurrent::Map` (formerly ThreadSafe::Cache)
+  - `Concurrent::Tuple`
+* Minor improvements to Concurrent::Map
+* Complete rewrite of `Exchanger`
+* Removed all deprecated code (classes, methods, constants, etc.)
+* Updated Agent, MutexAtomic, and BufferedChannel to inherit from Synchronization::Object.
+* Many improved tests
+* Some internal reorganization
+
+### Release v0.9.1 (09 August 2015)
 
 * Fixed a Rubiniux bug in synchronization object
 * Fixed all interpreter warnings (except circular references)

data/README.md

@@ -47,7 +47,15 @@
 
 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).
+Java 8 is preferred for JRuby but every Java version on which JRuby 9000 runs will be supported.
+
+## Thread Safety
+
+*Concurrent Ruby makes the strongest thread safety guarantees of any Ruby concurrency library. We are the only library with a published [memory model](https://github.com/ruby-concurrency/concurrent-ruby/blob/master/doc/synchronization.md) which provides consistent behavior and guarantees on all three of the main Ruby interpreters (MRI/CRuby, JRuby, and Rubinius).*
+
+Every abstraction in this library is thread safe. Similarly, all are deadlock free and many are fully lock free. Specific thread safety guarantees are documented with each abstraction.
+
+It is critical to remember, however, that Ruby is a language of mutable references. *No* concurrency library for Ruby can ever prevent the user from making thread safety mistakes (such as sharing a mutable object between threads and modifying it on both threads) or from creating deadlocks through incorrect use of locks. All the library can do is provide safe abstractions which encourage safe practices. Concurrent Ruby provides more safe concurrency abstractions than any other Ruby library, many of which support the mantra of ["Do not communicate by sharing memory; instead, share memory by communicating"](https://blog.golang.org/share-memory-by-communicating). Concurrent Ruby is also the only Ruby library which provides a full suite of thread safe and immutable variable types and data structures.
 
 ## Features & Documentation
 
@@ -61,55 +69,63 @@ This library contains a variety of concurrency abstractions at high and low leve
 
 #### General-purpose 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.
+* [Async](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Async.html): A mixin module that provides simple asynchronous behavior to a class. Loosely based on Erlang's [gen_server](http://www.erlang.org/doc/man/gen_server.html).
 * [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.
 * [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.
 
-#### Thread-safe Value Objects
+#### Thread-safe Value Objects, Structures, and Collections
+
+Collection classes that were originally part of the (deprecated) `thread_safe` gem:
 
-* `Maybe` A thread-safe, immutable object representing an optional value, based on
+* [Array](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Array.html) A thread-safe subclass of Ruby's standard [Array](http://ruby-doc.org/core-2.2.0/Array.html).
+* [Hash](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Hash.html) A thread-safe subclass of Ruby's standard [Hash](http://ruby-doc.org/core-2.2.0/Hash.html).
+* [Map](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Map.html) A hash-like object that should have much better performance characteristics, especially under high concurrency, than `Concurrent::Hash`.
+* [Tuple](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Tuple.html) A fixed size array with volatile (synchronized, thread safe) getters/setters.
+
+Value objects inspired by other languages:
+
+* [Maybe](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Maybe.html) 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).
+* [Delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.html) Lazy evaluation of a block yielding an immutable result. Based on Clojure's [delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.html).
+
+Structure classes derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html):
 
-#### Thread-safe Structures
+* [ImmutableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ImmutableStruct.html) Immutable struct where values are set at construction and cannot be changed later.
+* [MutableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutableStruct.html) Synchronized, mutable struct where values can be safely changed at any time.
+* [SettableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/SettableStruct.html) Synchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.
 
-Derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html):
+Thread-safe variables:
 
-* `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.
+* [Agent](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Agent.html): A way to manage shared, mutable, *asynchronous*, independent, state. Based on Clojure's [Agent](http://clojure.org/agents).
+* [Atom](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Atom.html): A way to manage shared, mutable, *synchronous*, independent state. Based on Clojure's [Atom](http://clojure.org/atoms).
+* [AtomicBoolean](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicBoolean.html) A boolean value that can be updated atomically.
+* [AtomicFixnum](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicFixnum.html) A numeric value that can be updated atomically.
+* [AtomicReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutexAtomic.html) An object reference that may be updated atomically.
+* [Exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html) A synchronization point at which threads can pair and swap elements within pairs. Based on Java's [Exchanger](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html).
+* [MVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MVar.html) A synchronized single element container. Based on Haskell's [MVar](https://hackage.haskell.org/package/base-4.8.1.0/docs/Control-Concurrent-MVar.html) and Scala's [MVar](http://docs.typelevel.org/api/scalaz/nightly/index.html#scalaz.concurrent.MVar$).
+* [ThreadLocalVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html) A variable where the value is different for each thread.
+* [TVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) A transactional variable implementing software transactional memory (STM). Based on Clojure's [Ref](http://clojure.org/refs).
 
 #### 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.
+* See the [thread pool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
 
 #### Thread Synchronization Classes and Algorithms
 
-* [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](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)
-* [ReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReadWriteLock.html)
-* [ReentrantReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReentrantReadWriteLock.html)
+* [CountDownLatch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html) A synchronization object that allows one thread to wait on multiple other threads.
+* [CyclicBarrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html) A synchronization aid that allows a set of threads to all wait for each other to reach a common barrier point.
+* [Event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html) Old school kernel-style event.
+* [IVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/IVar.html) Similar to a "future" but can be manually assigned once, after which it becomes immutable.
+* [ReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReadWriteLock.html) A lock that supports multiple readers but only one writer.
+* [ReentrantReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReentrantReadWriteLock.html) A read/write lock with reentrant and upgrade features.
+* [Semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html) A counting-based locking mechanism that uses permits.
 
 ### Edge Features
 
-These are available in the `concurrent-ruby-edge` companion gem, installed with `gem install concurrent-ruby-edge`.
+These are available in the `concurrent-ruby-edge` companion gem.
 
 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
@@ -117,74 +133,42 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
 
 * [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/FutureShortcuts.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 features **non-blocking** and **lock-free** with exception of obviously blocking
+* [New Future Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/FutureShortcuts.html):
+  Unified implementation of futures and promises which combines features of previous `Future`,
+  `Promise`, `IVar`, `Event`, `dataflow`, `Delay`, and `TimerTask` into a single framework. It extensively uses the
+  new synchronization layer to make all the features **non-blocking** and **lock-free**, with the exception of obviously blocking
   operations like `#wait`, `#value`. It also offers better performance.
-* [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)
+* [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/Channel.html):
+  Communicating Sequential Processes ([CSP](https://en.wikipedia.org/wiki/Communicating_sequential_processes)).
+  Functionally equivalent to Go [channels](https://tour.golang.org/concurrency/2) with additional
+  inspiration from Clojure [core.async](https://clojure.github.io/core.async/).
 * [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
-* [Atomic Markable Reference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/AtomicMarkableReference.html)
-* [LockFreeLinked Set](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
+* [AtomicMarkableReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/AtomicMarkableReference.html)
+* [LockFreeLinkedSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
 * [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeStack.html)
 
 #### 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.
+- **Actor** - Partial documentation and tests; depends on new future/promise framework; stability is good.
+- **Channel** - Brand new implementation; partial documentation and tests; stability is good.
+- **Future/Promise Framework** - API changes; partial documentation and tests; stability is good.
 - **LazyRegister** - Missing documentation and tests.
-- **AtomicMarkableReference, LockFreeLinkedSet, LockFreeStack** - Needs real world battle testing
+- **AtomicMarkableReference, LockFreeLinkedSet, LockFreeStack** - Need real world battle testing.
 
 ## Usage
 
-All abstractions within this gem can be loaded simply by requiring it:
+Everything within this gem can be loaded simply by requiring it:
 
 ```ruby
 require 'concurrent'
 ```
 
-To reduce the amount of code loaded at runtime, subsets of this gem can be required:
+To use the tools in the Edge gem it must be required separately:
 
 ```ruby
-require 'concurrent'                # everything
-
-# groups
-
-require 'concurrent/atomics'        # atomic and thread synchronization classes
-require 'concurrent/executors'      # Thread pools and other executors
-
-# 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/channel '       # Concurrent::Channel and supporting code
+require 'concurrent-edge'
 ```
 
 If the library does not behave as expected, `Concurrent.use_stdlib_logger(Logger::DEBUG)` could help to reveal the problem.
@@ -203,6 +187,23 @@ gem 'concurrent-ruby'
 
 and run `bundle install` from your shell.
 
+### Edge Gem Installation
+
+The Edge gem must be installed separately from the core gem:
+
+```shell
+gem install concurrent-ruby-edge
+```
+
+or add the following line to Gemfile:
+
+```ruby
+gem 'concurrent-ruby-edge'
+```
+
+and run `bundle install` from your shell.
+
+
 ### C Extensions for MRI
 
 Potential performance improvements may be achieved under MRI by installing optional C extensions.
@@ -236,55 +237,20 @@ and load the appropriate C extensions.
 No gems should depend on `concurrent-ruby-ext`. Doing so will force C extensions on your users.
 The best practice is to depend on `concurrent-ruby` and let users to decide if they want C extensions.
 
-### Building
-
-All published versions of this gem (core, extension, and several platform-specific packages) are compiled,
-packaged, tested, and published using an open, [automated process](https://github.com/ruby-concurrency/rake-compiler-dev-box).
-This process can also be used to create pre-compiled binaries of the extension gem for virtally
-any platform. *Documentation is forthcoming...*
-
-```
-*MRI only*
-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*
-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*
-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*
-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) (creator)
+* [Petr Chalupa](https://github.com/pitr-ch)
 * [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)
+* [Lucas Allan](https://github.com/lucasallan)
 
-## Contributing
+### Special Thanks
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+* [Brian Durand](https://github.com/bdurand) for the `ref` gem
+* [Charles Oliver Nutter](https://github.com/headius) for the `atomic` and `thread_safe` gems
+* [thedarkone](https://github.com/thedarkone) for the `thread_safe` gem
 
 ## License and Copyright
 

data/lib/concurrent.rb

@@ -1,19 +1,23 @@
 require 'concurrent/version'
-
-require 'concurrent/synchronization'
-
+require 'concurrent/constants'
+require 'concurrent/errors'
 require 'concurrent/configuration'
 
 require 'concurrent/atomics'
-require 'concurrent/errors'
 require 'concurrent/executors'
-require 'concurrent/utilities'
+require 'concurrent/synchronization'
 
 require 'concurrent/atomic/atomic_reference'
+require 'concurrent/agent'
 require 'concurrent/atom'
+require 'concurrent/array'
+require 'concurrent/hash'
+require 'concurrent/map'
+require 'concurrent/tuple'
 require 'concurrent/async'
 require 'concurrent/dataflow'
 require 'concurrent/delay'
+require 'concurrent/exchanger'
 require 'concurrent/future'
 require 'concurrent/immutable_struct'
 require 'concurrent/ivar'
@@ -26,6 +30,11 @@ require 'concurrent/settable_struct'
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
 
+require 'concurrent/thread_safe/synchronized_delegator'
+require 'concurrent/thread_safe/util'
+
+require 'concurrent/options'
+
 # @!macro [new] internal_implementation_note
 #
 #   @note **Private Implementation:** This abstraction is a private, internal

data/lib/concurrent/agent.rb

@@ -0,0 +1,587 @@
+require 'concurrent/configuration'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/atomic/thread_local_var'
+require 'concurrent/collection/copy_on_write_observer_set'
+require 'concurrent/concern/observable'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # `Agent` is inspired by Clojure's [agent](http://clojure.org/agents)
+  # function. An agent is a shared, mutable variable providing independent,
+  # uncoordinated, *asynchronous* change of individual values. Best used when
+  # the value will undergo frequent, complex updates. Suitable when the result
+  # of an update does not need to be known immediately. `Agent` is (mostly)
+  # functionally equivalent to Clojure's agent, except where the runtime
+  # prevents parity.
+  #
+  # Agents are reactive, not autonomous - there is no imperative message loop
+  # and no blocking receive. The state of an Agent should be itself immutable
+  # and the `#value` of an Agent is always immediately available for reading by
+  # any thread without any messages, i.e. observation does not require
+  # cooperation or coordination.
+  #
+  # Agent action dispatches are made using the various `#send` methods. These
+  # methods always return immediately. At some point later, in another thread,
+  # the following will happen:
+  #
+  # 1. The given `action` will be applied to the state of the Agent and the
+  #    `args`, if any were supplied.
+  # 2. The return value of `action` will be passed to the validator lambda,
+  #    if one has been set on the Agent.
+  # 3. If the validator succeeds or if no validator was given, the return value
+  #    of the given `action` will become the new `#value` of the Agent. See
+  #    `#initialize` for details.
+  # 4. If any observers were added to the Agent, they will be notified. See
+  #    `#add_observer` for details.
+  # 5. If during the `action` execution any other dispatches are made (directly
+  #    or indirectly), they will be held until after the `#value` of the Agent
+  #    has been changed.
+  #
+  # If any exceptions are thrown by an action function, no nested dispatches
+  # will occur, and the exception will be cached in the Agent itself. When an
+  # Agent has errors cached, any subsequent interactions will immediately throw
+  # an exception, until the agent's errors are cleared. Agent errors can be
+  # examined with `#error` and the agent restarted with `#restart`.
+  #
+  # The actions of all Agents get interleaved amongst threads in a thread pool.
+  # At any point in time, at most one action for each Agent is being executed.
+  # Actions dispatched to an agent from another single agent or thread will
+  # occur in the order they were sent, potentially interleaved with actions
+  # dispatched to the same agent from other sources. The `#send` method should
+  # be used for actions that are CPU limited, while the `#send_off` method is
+  # appropriate for actions that may block on IO.
+  #
+  # Unlike in Clojure, `Agent` cannot participate in `Concurrent::TVar` transactions.
+  #
+  # ## Example
+  #
+  # ```
+  # def next_fibonacci(set = nil)
+  #   return [0, 1] if set.nil?
+  #   set + [set[-2..-1].reduce{|sum,x| sum + x }]
+  # end
+  #
+  # # create an agent with an initial value
+  # agent = Concurrent::Agent.new(next_fibonacci)
+  #
+  # # send a few update requests
+  # 5.times do
+  #   agent.send{|set| next_fibonacci(set) }
+  # end
+  #
+  # # wait for them to complete
+  # agent.await
+  #
+  # # get the current value
+  # agent.value #=> [0, 1, 1, 2, 3, 5, 8]
+  # ```
+  #
+  # ## Observation
+  #
+  # Agents support observers through the {Concurrent::Observable} mixin module.
+  # Notification of observers occurs every time an action dispatch returns and
+  # the new value is successfully validated. Observation will *not* occur if the
+  # action raises an exception, if validation fails, or when a {#restart} occurs.
+  #
+  # When notified the observer will receive three arguments: `time`, `old_value`,
+  # and `new_value`. The `time` argument is the time at which the value change
+  # occurred. The `old_value` is the value of the Agent when the action began
+  # processing. The `new_value` is the value to which the Agent was set when the
+  # action completed. Note that `old_value` and `new_value` may be the same.
+  # This is not an error. It simply means that the action returned the same
+  # value.
+  #
+  # ## Nested Actions
+  #
+  # It is possible for an Agent action to post further actions back to itself.
+  # The nested actions will be enqueued normally then processed *after* the
+  # outer action completes, in the order they were sent, possibly interleaved
+  # with action dispatches from other threads. Nested actions never deadlock
+  # with one another and a failure in a nested action will never affect the
+  # outer action.
+  #
+  # Nested actions can be called using the Agent reference from the enclosing
+  # scope or by passing the reference in as a "send" argument. Nested actions
+  # cannot be post using `self` from within the action block/proc/lambda; `self`
+  # in this context will not reference the Agent. The preferred method for
+  # dispatching nested actions is to pass the Agent as an argument. This allows
+  # Ruby to more effectively manage the closing scope.
+  #
+  # Prefer this:
+  #
+  # ```
+  # agent = Concurrent::Agent.new(0)
+  # agent.send(agent) do |value, this|
+  #   this.send {|v| v + 42 }
+  #   3.14
+  # end
+  # agent.value #=> 45.14
+  # ```
+  #
+  # Over this:
+  #
+  # ```
+  # agent = Concurrent::Agent.new(0)
+  # agent.send do |value|
+  #   agent.send {|v| v + 42 }
+  #   3.14
+  # end
+  # ```
+  #
+  # @!macro [new] agent_await_warning
+  #
+  #   **NOTE** Never, *under any circumstances*, call any of the "await" methods
+  #   ({#await}, {#await_for}, {#await_for!}, and {#wait}) from within an action
+  #   block/proc/lambda. The call will block the Agent and will always fail.
+  #   Calling either {#await} or {#wait} (with a timeout of `nil`) will
+  #   hopelessly deadlock the Agent with no possibility of recovery.
+  #
+  # @!macro thread_safe_variable_comparison
+  #
+  # @see http://clojure.org/Agents Clojure Agents
+  # @see http://clojure.org/state Values and Change - Clojure's approach to Identity and State
+  class Agent < Synchronization::LockableObject
+    include Concern::Observable
+
+    ERROR_MODES = [:continue, :fail].freeze
+    private_constant :ERROR_MODES
+
+    AWAIT_FLAG = Object.new
+    private_constant :AWAIT_FLAG
+
+    AWAIT_ACTION = ->(value, latch) { latch.count_down; AWAIT_FLAG }
+    private_constant :AWAIT_ACTION
+
+    DEFAULT_ERROR_HANDLER = ->(agent, error) { nil }
+    private_constant :DEFAULT_ERROR_HANDLER
+
+    DEFAULT_VALIDATOR = ->(value) { true }
+    private_constant :DEFAULT_VALIDATOR
+
+    Job = Struct.new(:action, :args, :executor, :caller)
+    private_constant :Job
+
+    # Raised during action processing or any other time in an Agent's lifecycle.
+    class Error < StandardError
+      def initialize(message = nil)
+        message ||= 'agent must be restarted before jobs can post'
+        super(message)
+      end
+    end
+
+    # Raised when a new value obtained during action processing or at `#restart`
+    # fails validation.
+    class ValidationError < Error
+      def initialize(message = nil)
+        message ||= 'invalid value'
+        super(message)
+      end
+    end
+
+    # The error mode this Agent is operating in. See {#initialize} for details.
+    attr_reader :error_mode
+
+    # Create a new `Agent` with the given initial value and options.
+    #
+    # The `:validator` option must be `nil` or a side-effect free proc/lambda
+    # which takes one argument. On any intended value change the validator, if
+    # provided, will be called. If the new value is invalid the validator should
+    # return `false` or raise an error.
+    #
+    # The `:error_handler` option must be `nil` or a proc/lambda which takes two
+    # arguments. When an action raises an error or validation fails, either by
+    # returning false or raising an error, the error handler will be called. The
+    # arguments to the error handler will be a reference to the agent itself and
+    # the error object which was raised.
+    #
+    # The `:error_mode` may be either `:continue` (the default if an error
+    # handler is given) or `:fail` (the default if error handler nil or not
+    # given).
+    #
+    # If an action being run by the agent throws an error or doesn't pass
+    # validation the error handler, if present, will be called. After the
+    # handler executes if the error mode is `:continue` the Agent will continue
+    # as if neither the action that caused the error nor the error itself ever
+    # happened.
+    #
+    # If the mode is `:fail` the Agent will become {#failed?} and will stop
+    # accepting new action dispatches. Any previously queued actions will be
+    # held until {#restart} is called. The {#value} method will still work,
+    # returning the value of the Agent before the error.
+    #
+    # @param [Object] initial the initial value
+    # @param [Hash] opts the configuration options
+    #
+    # @option opts [Symbol] :error_mode either `:continue` or `:fail`
+    # @option opts [nil, Proc] :error_handler the (optional) error handler
+    # @option opts [nil, Proc] :validator the (optional) validation procedure
+    def initialize(initial, opts = {})
+      super()
+      synchronize { ns_initialize(initial, opts) }
+    end
+
+    # The current value (state) of the Agent, irrespective of any pending or
+    # in-progress actions. The value is always available and is non-blocking.
+    #
+    # @return [Object] the current value
+    def value
+      @current.value # TODO (pitr 12-Sep-2015): broken unsafe read?
+    end
+
+    alias_method :deref, :value
+
+    # When {#failed?} and {#error_mode} is `:fail`, returns the error object
+    # which caused the failure, else `nil`. When {#error_mode} is `:continue`
+    # will *always* return `nil`.
+    #
+    # @return [nil, Error] the error which caused the failure when {#failed?}
+    def error
+      @error.value
+    end
+
+    alias_method :reason, :error
+
+    # @!macro [attach] agent_send
+    #
+    #   Dispatches an action to the Agent and returns immediately. Subsequently,
+    #   in a thread from a thread pool, the {#value} will be set to the return
+    #   value of the action. Action dispatches are only allowed when the Agent
+    #   is not {#failed?}.
+    #
+    #   The action must be a block/proc/lambda which takes 1 or more arguments.
+    #   The first argument is the current {#value} of the Agent. Any arguments
+    #   passed to the send method via the `args` parameter will be passed to the
+    #   action as the remaining arguments. The action must return the new value
+    #   of the Agent.
+    #
+    #   * {#send} and {#send!} should be used for actions that are CPU limited
+    #   * {#send_off}, {#send_off!}, and {#<<} are appropriate for actions that
+    #     may block on IO
+    #   * {#send_via} and {#send_via!} are used when a specific executor is to
+    #     be used for the action
+    #
+    #   @param [Array<Object>] args zero or more arguments to be passed to
+    #     the action
+    #   @param [Proc] action the action dispatch to be enqueued
+    #
+    #   @yield [agent, value, *args] process the old value and return the new
+    #   @yieldparam [Object] value the current {#value} of the Agent
+    #   @yieldparam [Array<Object>] args zero or more arguments to pass to the
+    #     action
+    #   @yieldreturn [Object] the new value of the Agent
+    #
+    # @!macro [attach] send_return
+    #   @return [Boolean] true if the action is successfully enqueued, false if
+    #     the Agent is {#failed?}
+    def send(*args, &action)
+      enqueue_action_job(action, args, Concurrent.global_fast_executor)
+    end
+
+    # @!macro agent_send
+    #
+    # @!macro [attach] send_bang_return_and_raise
+    #   @return [Boolean] true if the action is successfully enqueued
+    #   @raise [Concurrent::Agent::Error] if the Agent is {#failed?}
+    def send!(*args, &action)
+      raise Error.new unless send(*args, &action)
+      true
+    end
+
+    # @!macro agent_send
+    # @!macro send_return
+    def send_off(*args, &action)
+      enqueue_action_job(action, args, Concurrent.global_io_executor)
+    end
+
+    alias_method :post, :send_off
+
+    # @!macro agent_send
+    # @!macro send_bang_return_and_raise
+    def send_off!(*args, &action)
+      raise Error.new unless send_off(*args, &action)
+      true
+    end
+
+    # @!macro agent_send
+    # @!macro send_return
+    # @param [Concurrent::ExecutorService] executor the executor on which the
+    #   action is to be dispatched
+    def send_via(executor, *args, &action)
+      enqueue_action_job(action, args, executor)
+    end
+
+    # @!macro agent_send
+    # @!macro send_bang_return_and_raise
+    # @param [Concurrent::ExecutorService] executor the executor on which the
+    #   action is to be dispatched
+    def send_via!(executor, *args, &action)
+      raise Error.new unless send_via(executor, *args, &action)
+      true
+    end
+
+    # Dispatches an action to the Agent and returns immediately. Subsequently,
+    # in a thread from a thread pool, the {#value} will be set to the return
+    # value of the action. Appropriate for actions that may block on IO.
+    #
+    # @param [Proc] action the action dispatch to be enqueued
+    # @return [Concurrent::Agent] self
+    # @see {#send_off}
+    def <<(action)
+      send_off(&action)
+      self
+    end
+
+    # Blocks the current thread (indefinitely!) until all actions dispatched
+    # thus far, from this thread or nested by the Agent, have occurred. Will
+    # block when {#failed?}. Will never return if a failed Agent is {#restart}
+    # with `:clear_actions` true.
+    #
+    # Returns a reference to `self` to support method chaining:
+    #
+    # ```
+    # current_value = agent.await.value
+    # ```
+    #
+    # @return [Boolean] self
+    #
+    # @!macro agent_await_warning
+    def await
+      wait(nil)
+      self
+    end
+
+    # Blocks the current thread until all actions dispatched thus far, from this
+    # thread or nested by the Agent, have occurred, or the timeout (in seconds)
+    # has elapsed.
+    #
+    # @param [Float] timeout the maximum number of seconds to wait
+    # @return [Boolean] true if all actions complete before timeout else false
+    #
+    # @!macro agent_await_warning
+    def await_for(timeout)
+      wait(timeout.to_f)
+    end
+
+    # Blocks the current thread until all actions dispatched thus far, from this
+    # thread or nested by the Agent, have occurred, or the timeout (in seconds)
+    # has elapsed.
+    #
+    # @param [Float] timeout the maximum number of seconds to wait
+    # @return [Boolean] true if all actions complete before timeout
+    #
+    # @raise [Concurrent::TimeoutError] when timout is reached
+    #
+    # @!macro agent_await_warning
+    def await_for!(timeout)
+      raise Concurrent::TimeoutError unless wait(timeout.to_f)
+      true
+    end
+
+    # Blocks the current thread until all actions dispatched thus far, from this
+    # thread or nested by the Agent, have occurred, or the timeout (in seconds)
+    # has elapsed. Will block indefinitely when timeout is nil or not given.
+    #
+    # Provided mainly for consistency with other classes in this library. Prefer
+    # the various `await` methods instead.
+    #
+    # @param [Float] timeout the maximum number of seconds to wait
+    # @return [Boolean] true if all actions complete before timeout else false
+    #
+    # @!macro agent_await_warning
+    def wait(timeout = nil)
+      latch = Concurrent::CountDownLatch.new(1)
+      enqueue_await_job(latch)
+      latch.wait(timeout)
+    end
+
+    # Is the Agent in a failed state?
+    #
+    # @see {#restart}
+    def failed?
+      !@error.value.nil?
+    end
+
+    alias_method :stopped?, :failed?
+
+    # When an Agent is {#failed?}, changes the Agent {#value} to `new_value`
+    # then un-fails the Agent so that action dispatches are allowed again. If
+    # the `:clear_actions` option is give and true, any actions queued on the
+    # Agent that were being held while it was failed will be discarded,
+    # otherwise those held actions will proceed. The `new_value` must pass the
+    # validator if any, or `restart` will raise an exception and the Agent will
+    # remain failed with its old {#value} and {#error}. Observers, if any, will
+    # not be notified of the new state.
+    #
+    # @param [Object] new_value the new value for the Agent once restarted
+    # @param [Hash] opts the configuration options
+    # @option opts [Symbol] :clear_actions true if all enqueued but unprocessed
+    #   actions should be discarded on restart, else false (default: false)
+    # @return [Boolean] true
+    #
+    # @raise [Concurrent:AgentError] when not failed
+    def restart(new_value, opts = {})
+      clear_actions = opts.fetch(:clear_actions, false)
+      synchronize do
+        raise Error.new('agent is not failed') unless failed?
+        raise ValidationError unless ns_validate(new_value)
+        @current.value = new_value
+        @error.value   = nil
+        @queue.clear if clear_actions
+        ns_post_next_job unless @queue.empty?
+      end
+      true
+    end
+
+    class << self
+
+      # Blocks the current thread (indefinitely!) until all actions dispatched
+      # thus far to all the given Agents, from this thread or nested by the
+      # given Agents, have occurred. Will block when any of the agents are
+      # failed. Will never return if a failed Agent is restart with
+      # `:clear_actions` true.
+      #
+      # @param [Array<Concurrent::Agent>] agents the Agents on which to wait
+      # @return [Boolean] true
+      #
+      # @!macro agent_await_warning
+      def await(*agents)
+        agents.each { |agent| agent.await }
+        true
+      end
+
+      # Blocks the current thread until all actions dispatched thus far to all
+      # the given Agents, from this thread or nested by the given Agents, have
+      # occurred, or the timeout (in seconds) has elapsed.
+      #
+      # @param [Float] timeout the maximum number of seconds to wait
+      # @param [Array<Concurrent::Agent>] agents the Agents on which to wait
+      # @return [Boolean] true if all actions complete before timeout else false
+      #
+      # @!macro agent_await_warning
+      def await_for(timeout, *agents)
+        end_at = Concurrent.monotonic_time + timeout.to_f
+        ok     = agents.length.times do |i|
+          break false if (delay = end_at - Concurrent.monotonic_time) < 0
+          break false unless agents[i].await_for(delay)
+        end
+        !!ok
+      end
+
+      # Blocks the current thread until all actions dispatched thus far to all
+      # the given Agents, from this thread or nested by the given Agents, have
+      # occurred, or the timeout (in seconds) has elapsed.
+      #
+      # @param [Float] timeout the maximum number of seconds to wait
+      # @param [Array<Concurrent::Agent>] agents the Agents on which to wait
+      # @return [Boolean] true if all actions complete before timeout
+      #
+      # @raise [Concurrent::TimeoutError] when timout is reached
+      # @!macro agent_await_warning
+      def await_for!(timeout, *agents)
+        raise Concurrent::TimeoutError unless await_for(timeout, *agents)
+        true
+      end
+    end
+
+    private
+
+    def ns_initialize(initial, opts)
+      @error_mode    = opts[:error_mode]
+      @error_handler = opts[:error_handler]
+
+      if @error_mode && !ERROR_MODES.include?(@error_mode)
+        raise ArgumentError.new('unrecognized error mode')
+      elsif @error_mode.nil?
+        @error_mode = @error_handler ? :continue : :fail
+      end
+
+      @error_handler ||= DEFAULT_ERROR_HANDLER
+      @validator     = opts.fetch(:validator, DEFAULT_VALIDATOR)
+      @current       = Concurrent::AtomicReference.new(initial)
+      @error         = Concurrent::AtomicReference.new(nil)
+      @caller        = Concurrent::ThreadLocalVar.new(nil)
+      @queue         = []
+
+      self.observers = Collection::CopyOnNotifyObserverSet.new
+    end
+
+    def enqueue_action_job(action, args, executor)
+      raise ArgumentError.new('no action given') unless action
+      job = Job.new(action, args, executor, @caller.value || Thread.current.object_id)
+      synchronize { ns_enqueue_job(job) }
+    end
+
+    def enqueue_await_job(latch)
+      synchronize do
+        if (index = ns_find_last_job_for_thread)
+          job = Job.new(AWAIT_ACTION, [latch], Concurrent.global_immediate_executor,
+                        Thread.current.object_id)
+          ns_enqueue_job(job, index+1)
+        else
+          latch.count_down
+          true
+        end
+      end
+    end
+
+    def ns_enqueue_job(job, index = nil)
+      # a non-nil index means this is an await job
+      return false if index.nil? && failed?
+      index ||= @queue.length
+      @queue.insert(index, job)
+      # if this is the only job, post to executor
+      ns_post_next_job if @queue.length == 1
+      true
+    end
+
+    def ns_post_next_job
+      @queue.first.executor.post { execute_next_job }
+    end
+
+    def execute_next_job
+      job       = synchronize { @queue.first }
+      old_value = @current.value
+
+      @caller.value = job.caller # for nested actions
+      new_value     = job.action.call(old_value, *job.args)
+      @caller.value = nil
+
+      return if new_value == AWAIT_FLAG
+
+      if ns_validate(new_value)
+        @current.value = new_value
+        observers.notify_observers(Time.now, old_value, new_value)
+      else
+        handle_error(ValidationError.new)
+      end
+    rescue => error
+      handle_error(error)
+    ensure
+      synchronize do
+        @queue.shift
+        unless failed? || @queue.empty?
+          ns_post_next_job
+        end
+      end
+    end
+
+    def ns_validate(value)
+      @validator.call(value)
+    rescue
+      false
+    end
+
+    def handle_error(error)
+      # stop new jobs from posting
+      @error.value = error if @error_mode == :fail
+      @error_handler.call(self, error)
+    rescue
+      # do nothing
+    end
+
+    def ns_find_last_job_for_thread
+      @queue.rindex { |job| job.caller == Thread.current.object_id }
+    end
+  end
+end