Merge pull request #323 from ruby-concurrency/readme-changelog

Began updating README and CHANGELOG

Author: jdantonio

CHANGELOG.md

@@ -1,4 +1,4 @@
-### Next Release v0.9.0 (Target Date: 5 April 2015)
+### Next Release v0.9.0 (Target Date: 7 June 2015)
 
 * Pure Java implementations of
   - `AtomicBoolean`
@@ -20,7 +20,7 @@
 * 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
+* 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)
@@ -43,6 +43,55 @@
 * 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)
 

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,7 +50,7 @@ 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
 
 * [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.
@@ -60,47 +60,58 @@ This library contains a variety of concurrency abstractions at high and low leve
 * [ScheduledTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ScheduledTask.html): Like a Future scheduled for a specific future time.
 * [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html): A Thread that periodically wakes up to perform work at regular intervals. 
 
-### Java-inspired ThreadPools and other executors
+#### 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 Structures
 
-* Thread-safe structure classes derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html)
+Derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html):
 
 * `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.
 
-### Thread synchronization classes and algorithms
+#### Java-inspired ThreadPools and Other Executors
+
+* See [ThreadPool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
+
+#### Thread 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)
-* [Timeout](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timeout-class_method)
-* [Timer](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timer-class_method)
 
-### Thread-safe variables
+#### 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)
-* [Delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.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)
 
-### Edge features
+### Edge Features
 
-They are available in the `concurrent-ruby-edge` companion gem, install with `gem install concurrent-ruby-edge`.
+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).
@@ -114,6 +125,17 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
   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
 
 All abstractions within this gem can be loaded simply by requiring it:
@@ -131,32 +153,36 @@ require 'concurrent'                # everything
 
 require 'concurrent/atomics'        # atomic and thread synchronization classes
 require 'concurrent/executors'      # Thread pools and other executors
-require 'concurrent/utilities'      # utility methods such as processor count and timers
 
 # individual abstractions
 
-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/exchanger'      # Concurrent::Exchanger
-require 'concurrent/future'         # Concurrent::Future
-require 'concurrent/ivar'           # Concurrent::IVar
-require 'concurrent/lazy_register'  # Concurrent::LazyRegister
-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/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/exchanger'      # Concurrent::Exchanger
+require 'concurrent/lazy_register'  # Concurrent::LazyRegister
 ```
 
-If the library does not behave as expected, `Concurrent.use_stdlib_logger(Logger::DEBUG)` could help to revel the problem.
+If the library does not behave as expected, `Concurrent.use_stdlib_logger(Logger::DEBUG)` could help to reveal the problem.
 
 ## Installation
 
@@ -241,7 +267,7 @@ bundle exec 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`)

lib/concurrent/edge/future.rb

@@ -8,7 +8,7 @@ module Concurrent
   # Provides edge features, which will be added to or replace features in main gem.
   #
   # Contains 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
+  # `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 (exception being `#wait` and similar methods where it's
   # intended).