ruby-concurrency · pitr-ch · Dec 27, 2016 · Mar 14, 2016 · Mar 14, 2016 · Mar 14, 2016
diff --git a/.yardopts b/.yardopts
@@ -5,10 +5,12 @@
 --title=Concurrent Ruby
 --template default
 --template-path ./yard-template
+--default-return undocumented
 
 ./lib/**/*.rb
 ./ext/concurrent_ruby_ext/**/*.c
 -
 doc/thread_pools.md
+doc/promises.out.md
 README.md
 LICENSE.txt
diff --git a/Gemfile b/Gemfile
@@ -4,18 +4,20 @@ gemspec name: 'concurrent-ruby'
 gemspec name: 'concurrent-ruby-edge'
 
 group :development do
-  gem 'rake', '~> 10.4.2'
+  gem 'rake', '~> 10.0'
   gem 'rake-compiler', '~> 0.9.5'
   gem 'rake-compiler-dock', '~> 0.4.3'
   gem 'gem-compiler', '~> 0.3.0'
-  gem 'benchmark-ips', '~> 2.2.0'
+  gem 'benchmark-ips', '~> 2.7'
 
   # documentation
   gem 'countloc', '~> 0.4.0', :platforms => :mri, :require => false
-  gem 'yard', '~> 0.8.7.6', :require => false
+  gem 'yard', '~> 0.8.0', :require => false
   # TODO (pitr-ch 15-Oct-2016): does not work on 1.9.3 anymore
-  gem 'inch', '~> 0.6.3', :platforms => :mri, :require => false
-  gem 'redcarpet', '~> 3.3.2', platforms: :mri # understands github markdown
+  # TODO remove, reports private classes as undocumented
+  gem 'inch', '~> 0.7.0', :platforms => :mri, :require => false
+  gem 'redcarpet', '~> 3.3', platforms: :mri # understands github markdown
+  gem 'md-ruby-eval'
 end
 
 group :testing do

diff --git a/README.md b/README.md
@@ -9,39 +9,28 @@
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
 [![Gitter chat](https://img.shields.io/badge/IRC%20(gitter)-devs%20%26%20users-brightgreen.svg)](https://gitter.im/ruby-concurrency/concurrent-ruby)
 
-<table>
-  <tr>
-    <td align="left" valign="top">
-      <p>
-        Modern concurrency tools for Ruby. Inspired by
-        <a href="http://www.erlang.org/doc/reference_manual/processes.html">Erlang</a>,
-        <a href="http://clojure.org/concurrent_programming">Clojure</a>,
-        <a href="http://akka.io/">Scala</a>,
-        <a href="http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell">Haskell</a>,
-        <a href="http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx">F#</a>,
-        <a href="http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx">C#</a>,
-        <a href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html">Java</a>,
-        and classic concurrency patterns.
-      </p>
-      <p>
-        The design goals of this gem are:
-        <ul>
-          <li>Be an 'unopinionated' toolbox that provides useful utilities without debating which is better or why</li>
-          <li>Remain free of external gem dependencies</li>
-          <li>Stay true to the spirit of the languages providing inspiration</li>
-          <li>But implement in a way that makes sense for Ruby</li>
-          <li>Keep the semantics as idiomatic Ruby as possible</li>
-          <li>Support features that make sense in Ruby</li>
-          <li>Exclude features that don't make sense in Ruby</li>
-          <li>Be small, lean, and loosely coupled</li>
-        </ul>
-      </p>
-    </td>
-    <td align="right" valign="top">
-      <img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc/logo/concurrent-ruby-logo-300x300.png"/>
-    </td>
-  </tr>
-</table>
+Modern concurrency tools for Ruby. Inspired by
+[Erlang](http://www.erlang.org/doc/reference_manual/processes.html),
+[Clojure](http://clojure.org/concurrent_programming),
+[Scala](http://akka.io/),
+[Haskell](http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell),
+[F#](http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx),
+[C#](http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx),
+[Java](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html),
+and classic concurrency patterns.
+
+<img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc/logo/concurrent-ruby-logo-300x300.png" align="right" style="margin-left: 20px;" />
+
+The design goals of this gem are:
+
+* Be an 'unopinionated' toolbox that provides useful utilities without debating which is better or why
+* Remain free of external gem dependencies
+* 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
+* Support features that make sense in Ruby
+* Exclude features that don't make sense in Ruby
+* Be small, lean, and loosely coupled
 
 ### Supported Ruby versions
 
@@ -127,29 +116,30 @@ These features are under active development and may change frequently. They are
 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/FutureShortcuts.html):
+* [Promises Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promises.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.
+* [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html):
+  Implements the Actor Model, where concurrent actors exchange messages.
 * [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)
 * [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)
+* [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LockFreeStack.html)
 
 #### Statuses:
 
 *Why are these not in core?*
 
+- **Promises Framework** - They are being finalized to be able to be moved to core. They'll deprecate old 
+  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** - Need real world battle testing.
 

diff --git a/doc/future-promise.md b/doc/future-promise.md
diff --git a/doc/promises-main.md b/doc/promises-main.md
@@ -0,0 +1,61 @@
+Promises is a new framework unifying former tools `Concurrent::Future`,
+`Concurrent::Promise`, `Concurrent::IVar`, `Concurrent::Event`,
+`Concurrent.dataflow`, `Delay`, and `TimerTask` of concurrent-ruby. It
+extensively uses the new synchronization layer to make all the methods
+*lock-free* (with the exception of obviously blocking operations like `#wait`,
+`#value`, etc.). As a result it lowers danger of deadlocking and offers
+better performance.
+
+It provides similar tools as other promise libraries do, users coming from
+other languages and other promise libraries will find the same tools here
+(probably named differently though). The naming conventions were borrowed
+heavily from JS promises.
+
+This framework, however, is not just a re-implementation of other promise
+library, it draws inspiration from many other promise libraries, adds new
+ideas, and is integrated with other abstractions like actors and channels.
+
+Therefore it is likely that user will find a suitable solution for a problem in
+this framework. If the problem is simple user can pick one suitable
+abstraction, e.g. just promises or actors. If the problem is complex user can
+combine parts (promises, channels, actors) which were designed to work together
+well to a solution. Rather than having to combine fragilely independent tools.
+
+This framework allows its users to:
+
+-   Process tasks asynchronously
+-   Chain, branch, and zip the asynchronous tasks together
+    -   Therefore, to create directed acyclic graph (hereafter DAG) of tasks
+-   Create delayed tasks (or delayed DAG of tasks)
+-   Create scheduled tasks (or delayed DAG of tasks)
+-   Deal with errors through rejections
+-   Reduce danger of deadlocking
+-   Control the concurrency level of tasks
+-   Simulate thread-like processing without occupying threads
+    -   It allows to create tens of thousands simulations on one thread 
+        pool
+    -   It works well on all Ruby implementations
+-   Use actors to maintain isolated states and to seamlessly combine 
+    it with promises
+-   Build parallel processing stream system with back 
+    pressure (parts, which are not keeping up, signal to the other parts of the 
+    system to slow down).
+
+**The guide is best place to start with promises, see**
+**{file:doc/promises.out.md}.**
+
+# Main classes
+
+The main public user-facing classes are {Concurrent::Promises::Event} and
+{Concurrent::Promises::Future} which share common ancestor
+{Concurrent::Promises::AbstractEventFuture}.
+
+**{Concurrent::Promises::AbstractEventFuture}:** 
+> {include:Concurrent::Promises::AbstractEventFuture}
+
+**{Concurrent::Promises::Event}:** 
+> {include:Concurrent::Promises::Event}
+
+**{Concurrent::Promises::Future}:** 
+> {include:Concurrent::Promises::Future}
+