concurrently 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c58b0ef45ef3aa5d6e404f75b1592cbb415814e
-  data.tar.gz: bfb763b405d52aa08b52c0a8d423dbf6af9b2186
+  metadata.gz: a2433cf85e8e22dae4f8753c3f0bf8da68d0a307
+  data.tar.gz: 5fc75f82d8f23b989b9f73171cb11aa8dd7dc6e7
 SHA512:
-  metadata.gz: 8315e508fca33b19a367f37b38a29e39ace0eab55ad22eb4d0f3ce075b8878ad2066e8487f0cb0f0eec18ab9c93cfaf38dd2e61d9ab812127581535a6ca4ce0d
-  data.tar.gz: 1e3812a1f85bfcedae574ca758fe724af1e67a4377edf685066d9a800b53b8b12225244d0abcb34f00c9b8b1adb2036561dca36567eddb94656274d198072c21
+  metadata.gz: 6a69bfe30abb26229e12195fc514c1a2766c0cf1531a5c72a4bf872ef358deaa5e28eae06eae537786f82a159a0071695913b93cc367989d30b90cc489b18879
+  data.tar.gz: 28990344bb12e54ca9318f7396753e2a929cdbf80a8942ce2c00a2742b4e82a003c4e7c3db5e1f0001658bcbb815fd821cd3b1fc0bdbd8b1df0fddd2c30155cc

data/.gitignore

@@ -1,5 +1,5 @@
 /.bundle
 /.yardoc
 /doc
-/test/mruby/testenv/mruby
+/mruby_builds/*/
 /Gemfile.lock

data/.travis.yml

@@ -1,16 +1,21 @@
 language: ruby
 
-script: rake $TEST_RUBY:test
+script: rake test:$RUBY
 sudo: false
 
 rvm:
   - 2.4.1
   - 2.3.4
   - 2.2.7
+  - ruby-head
 
 env:
-  - TEST_RUBY=ruby
+  - RUBY=ruby
 
 matrix:
   include:
-  - env: TEST_RUBY=mruby
+  - env: RUBY=mruby[1.3.0]
+  - env: RUBY=mruby[master]
+  allow_failures:
+  - rvm: ruby-head
+  - env: RUBY=mruby[master]

data/README.md

@@ -2,84 +2,86 @@
 
 [![Build Status](https://secure.travis-ci.org/christopheraue/m-ruby-concurrently.svg?branch=master)](http://travis-ci.org/christopheraue/m-ruby-concurrently)
 
-Concurrently is a concurrency framework for Ruby and mruby. With it, concurrent
-code can be written sequentially similar to async/await.
-
-The concurrency primitive of Concurrently is the concurrent proc. It is very
-similar to a regular proc. Calling a concurrent proc creates a concurrent
-evaluation which is kind of a lightweight thread: It can wait for stuff without
-blocking other concurrent evaluations.
-
-Under the hood, concurrent procs are evaluated inside fibers. They can wait for
-readiness of I/O or a period of time (or the result of other concurrent
-evaluations). The interface is comparable to plain Ruby:
-
-<table>
-  <tr>
-    <th>Plain Ruby</th>
-    <th>Concurrently</th>
-  </tr>
-  <tr>
-    <td><code>Fiber.new(&block).resume</code></td>
-    <td><code>concurrent_proc(&block).call</code></td>
-  </tr>
-  <tr>
-    <td><code>IO.select([io])</code></td>
-    <td><code>io.await_readable</code></td>
-  </tr>
-  <tr>
-    <td><code>IO.select(nil, [io])</code></td>
-    <td><code>io.await_writable</code></td>
-  </tr>
-  <tr>
-    <td><code>IO.select(nil, nil, nil, seconds)</code></td>
-    <td><code>wait(seconds)</code></td>
-  </tr>
-</table>
-
-Beyond the mere beautification of the interface, Concurrently also takes care
-of the management of the event loop and the coordination between all concurrent
-evaluations.
-
-
-## A Basic Example
+Concurrently is a concurrency framework for Ruby and mruby built upon
+fibers. With it code can be evaluated independently in its own execution
+context similar to a thread. Execution contexts are called *evaluations* in
+Concurrently and are created with [Kernel#concurrently][]:
+
+```ruby
+hello = concurrently do
+  wait 0.2 # seconds
+  "hello"
+end
+
+world = concurrently do
+  wait 0.1 # seconds
+  "world"
+end
+
+puts "#{hello.await_result} #{world.await_result}" 
+```
+
+In this example we have three evaluations: The root evaluation and two more
+concurrent evaluations started by said root evaluation. The root evaluation
+waits until both concurrent evaluations were concluded and then prints "hello
+world".
+
+
+## Synchronization with events
+
+Evaluations can be synchronized with certain events by waiting for them. These
+events are:
+
+* an elapsed time period ([Kernel#wait][]),
+* readability and writability of IO ([IO#await_readable][],
+  [IO#await_writable][]) and
+* the result of another evaluation ([Concurrently::Proc::Evaluation#await_result][]).
+
+Since evaluations run independently they are not blocking other evaluations
+while waiting.
+
+
+## Concurrent I/O
+
+When doing I/O it is important to do it **non-blocking**. If the IO object is
+not ready use [IO#await_readable][] and [IO#await_writable][] to await
+readiness.
+
+For more about non-blocking I/O, see the core ruby docs for
+[IO#read_nonblock][] and [IO#write_nonblock][].
 
 This is a little server reading from an IO and printing the received messages:
 
 ```ruby
-server = concurrent_proc do |io|
+# Let's start with creating a pipe to connect client and server
+r,w = IO.pipe
+
+# Server:
+# We let the server code run concurrently so it runs independently. It reads
+# from the pipe non-blocking and awaits readability if the pipe is not readable.
+concurrently do
   while true
     begin
-      puts io.read_nonblock 32
+      puts r.read_nonblock 32
     rescue IO::WaitReadable
-      io.await_readable
+      r.await_readable
       retry
     end
   end
 end
-```
-
-Now, we create a pipe and start the server with the read end of it:
-
-```ruby
-r,w = IO.pipe
-server.call_detached r
-```
-
-Finally, we write messages to the write end of the pipe every 0.5 seconds:
 
-```ruby
+# Client:
+# The client writes to the pipe every 0.5 seconds
 puts "#{Time.now.strftime('%H:%M:%S.%L')} (Start time)"
-
 while true
   wait 0.5
   w.write Time.now.strftime('%H:%M:%S.%L')
 end
 ```
 
-The evaluation of the root fiber is effectively blocked by waiting or writing
-messages. But since the server runs concurrently it is not affected by this and
-happily prints its received messages.
+The root evaluation is effectively blocked by waiting or writing messages.
+But since the server runs concurrently it is not affected by this and happily
+prints its received messages.
 
 This is the output:
 
@@ -105,7 +107,7 @@ This is the output:
 ## Supported Ruby Versions
 
 * Ruby 2.2.7+
-* mruby 1.3+ (or mruby-head until mruby 1.3 is released)
+* mruby 1.3+
 
 
 ## Development
@@ -121,6 +123,14 @@ Concurrently is licensed under the Apache License, Version 2.0. Please see the
 file called LICENSE.
 
 
+[Kernel#concurrently]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Kernel#concurrently-instance_method
+[Kernel#wait]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Kernel#wait-instance_method
+[IO#await_readable]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#await_readable-instance_method
+[IO#await_writable]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#await_writable-instance_method
+[Concurrently::Proc::Evaluation#await_result]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/Proc/Evaluation#await_result-instance_method
+[IO#read_nonblock]: https://ruby-doc.org/core/IO.html#method-i-read_nonblock
+[IO#write_nonblock]: https://ruby-doc.org/core/IO.html#method-i-write_nonblock
+
 [installation]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/file/guides/Installation.md
 [overview]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/file/guides/Overview.md
 [documentation]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/index

data/RELEASE_NOTES.md

@@ -1,5 +1,20 @@
 # Release Notes
- 
+
+## 1.1.0 (2017-07-10)
+
+### Improvements
+* Improved error reporting
+* Improved benchmarks and profiling and made them work for mruby
+* Improved documentation
+* Improved overall performance
+
+### Extended [IO](http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO) interface
+* [#await_read](http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#await_read-instance_method)
+* [#await_written](http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#await_written-instance_method)
+
+### Extended [Kernel](http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Kernel) interface
+* [#await_fastest](http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Kernel#await_fastest-instance_method)
+
 ## 1.0.0 (2017-06-26)
 
 ### Added Support for

data/Rakefile

@@ -1,28 +1,112 @@
 Dir.chdir File.dirname __FILE__
 
-namespace :ruby do
-  task :test do
-    sh "rspec"
+perf_dir = File.expand_path "perf"
+
+# Ruby
+ruby = {
+  test: "rspec" ,
+  benchmark: "ruby -Iperf/Ruby -rstage",
+  profile: "ruby -Iperf/Ruby -rstage" }
+
+mruby_dir = File.expand_path "mruby_builds"
+mruby = {
+  src: "#{mruby_dir}/_source",
+  cfg: "#{mruby_dir}/build_config.rb",
+  test: "#{mruby_dir}/test/bin/mrbtest",
+  benchmark: "#{mruby_dir}/benchmark/bin/mruby",
+  profile: "#{mruby_dir}/profile/bin/mruby" }
+
+namespace :test do
+  desc "Run the Ruby test suite"
+  task :ruby do
+    sh ruby[:test]
+  end
+
+  desc "Run the mruby test suite"
+  task :mruby, [:reference] => "mruby:build" do
+    sh mruby[:test]
   end
 end
 
-namespace :mruby do
-  mruby_env = File.expand_path "test/mruby/testenv"
-  mruby_dir = "#{mruby_env}/mruby"
-  
-  file mruby_dir do
-    sh "git clone --depth=1 git://github.com/mruby/mruby.git #{mruby_dir}"
+desc "Run the Ruby and mruby test suites"
+task test: %w(test:ruby test:mruby)
+
+namespace :benchmark do
+  desc "Run the benchmark #{perf_dir}/benchmark_[name].rb with Ruby"
+  task :ruby, [:name, :batch_size] do |t, args|
+    args.with_defaults name: "wait_methods", batch_size: 100
+    file = "#{perf_dir}/benchmark_#{args.name}.rb"
+    sh "#{ruby[:benchmark]} #{file} #{args.batch_size}"
   end
 
-  task test: mruby_dir do
-    sh "cd #{mruby_dir} && MRUBY_CONFIG=#{mruby_env}/build_config.rb rake test"
+  desc "Run the benchmark #{perf_dir}/benchmark_[name].rb with mruby"
+  task :mruby, [:name, :batch_size] => "mruby:build" do |t, args|
+    args.with_defaults name: "wait_methods", batch_size: 100
+    file = "#{perf_dir}/benchmark_#{args.name}.rb"
+    sh "#{mruby[:benchmark]} #{file} #{args.batch_size}"
   end
+end
+
+desc "Run the benchmark #{perf_dir}/benchmark_[name].rb for Ruby and mruby"
+task :benchmark, [:name, :batch_size] => "mruby:build" do |t, args|
+  args.with_defaults name: "wait_methods", batch_size: 100
+  file = "#{perf_dir}/benchmark_#{args.name}.rb"
+  sh "#{ruby[:benchmark]} #{file} #{args.batch_size}", verbose: false
+  sh "#{mruby[:benchmark]} #{file} #{args.batch_size} skip_header", verbose: false
+end
 
-  task clean: mruby_dir do
-    sh "cd #{mruby_dir} && rake deep_clean"
+namespace :profile do
+  desc "Create a code profile by running #{perf_dir}/profile_[name].rb with Ruby"
+  task :ruby, [:name] do |t, args|
+    args.with_defaults name: "call"
+    file = "#{perf_dir}/profile_#{args.name}.rb"
+    sh "#{ruby[:profile]} #{file}"
+  end
+
+  desc "Create a code profile by running #{perf_dir}/profile_[name].rb with mruby"
+  task :mruby, [:name] => "mruby:build" do |t, args|
+    args.with_defaults name: "call"
+    file = "#{perf_dir}/profile_#{args.name}.rb"
+    sh "#{mruby[:profile]} #{file}"
   end
 end
 
-task test: %w(ruby:test mruby:test)
+namespace :mruby do
+  file mruby[:src] do
+    sh "git clone --depth=1 git://github.com/mruby/mruby.git #{mruby[:src]}"
+  end
+
+  desc "Checkout a tag or commit of the mruby source. Executes: git checkout reference"
+  task :checkout, [:reference] => mruby[:src] do |t, args|
+    args.with_defaults reference: 'master'
+    `cd #{mruby[:src]} && git fetch --tags`
+    current_ref = `cd #{mruby[:src]} && git rev-parse HEAD`
+    checkout_ref = `cd #{mruby[:src]} && git rev-parse #{args.reference}`
+    if checkout_ref != current_ref
+      Rake::Task['mruby:clean'].invoke
+      sh "cd #{mruby[:src]} && git checkout #{args.reference}"
+    end
+  end
+
+  desc "Build mruby"
+  task :build, [:reference] => :checkout do
+    sh "cd #{mruby[:src]} && MRUBY_CONFIG=#{mruby[:cfg]} rake"
+  end
+
+  desc "Clean the mruby build"
+  task clean: mruby[:src] do
+    sh "cd #{mruby[:src]} && MRUBY_CONFIG=#{mruby[:cfg]} rake deep_clean"
+  end
+
+  desc "Update the source of mruby"
+  task pull: :clean do
+    sh "cd #{mruby[:src]} && git pull"
+  end
+
+  desc "Delete the mruby source"
+  task delete: mruby[:src] do
+    sh "rm -rf #{mruby[:src]}"
+  end
+end
 
 task default: :test

data/concurrently.gemspec

@@ -4,19 +4,23 @@ Gem::Specification.new do |spec|
   spec.name         = "concurrently"
   spec.version      = Concurrently::VERSION
   spec.summary      = %q{A concurrency framework based on fibers}
-  spec.description  = <<-DESC
-Concurrently is a concurrency framework for Ruby and mruby. With it, concurrent
-code can be written sequentially similar to async/await.
+  spec.description  = <<'DESC'
+Concurrently is a concurrency framework for Ruby and mruby based on
+fibers. With it code can be evaluated independently in its own execution
+context similar to a thread:
 
-The concurrency primitive of Concurrently is the concurrent proc. It is very
-similar to a regular proc. Calling a concurrent proc creates a concurrent
-evaluation which is kind of a lightweight thread: It can wait for stuff without
-blocking other concurrent evaluations.
-
-Under the hood, concurrent procs are evaluated inside fibers. They can wait for
-readiness of I/O or a period of time (or the result of other concurrent
-evaluations).
-  DESC
+    hello = concurrently do
+      wait 0.2 # seconds
+      "hello"
+    end
+    
+    world = concurrently do
+      wait 0.1 # seconds
+      "world"
+    end
+    
+    puts "#{hello.await_result} #{world.await_result}"
+DESC
 
   spec.homepage      = "https://github.com/christopheraue/m-ruby-concurrently"
   spec.license       = "Apache-2.0"

data/ext/mruby/io.rb

@@ -29,7 +29,7 @@ class IO
     #
     # @see https://ruby-doc.org/core-1.9.3/IO.html#method-i-read_nonblock
     #   Ruby's documentation for IO#read_nonblock
-    def read_nonblock(maxlen, outbuf = nil)
+    def read_nonblock(maxlen, outbuf = '')
       if IO.select [self], nil, nil, 0
         sysread(maxlen, outbuf)
       else

data/guides/Overview.md

@@ -1,64 +1,123 @@
 # An Overview of Concurrently
 
-This document is meant as a general overview of what can be done with
-Concurrently and how all its parts work together. For more information and
-examples about a topic follow the interspersed links to the documentation.
+The [README][] already introduced the basic interface of Concurrently. 
+This document explores the underlying concepts and explains how all parts work
+together. For even more details and examples about a specific topic follow the
+interspersed links to the [API documentation][].
+
+Let's start with the concept of an *evaluation*.
+
 
 ## Evaluations
 
-An evaluation is an atomic thread of execution leading to a result. It is
-similar to a thread or a fiber. It can be suspended and resumed independently
-from other evaluations. It is also similar to a future or a promise by
-providing access to its future result or offering the ability to inject a
-result manually. Once the evaluation has a result it is *concluded*.
+An evaluation is an independent execution context. It is similar to a thread or
+a fiber since it can be suspended and resumed independently from other
+evaluations.
 
 Every ruby program already has an implicit [root evaluation][Concurrently::Evaluation]
-running. Calling a concurrent proc creates a [proc evaluation][Concurrently::Proc::Evaluation].
+running. Unless you explicitly tell your program to evaluate code concurrently
+it is evaluated in the root evaluation. The root evaluation runs as long as
+your program is running. Thus it is never concluded and its result cannot be
+awaited.
+
+Evaluating code with `concurrently(&block)` is done in its own type of
+[evaluation][Concurrently::Proc::Evaluation]. Contrary to the root evaluation,
+this evaluation has an end with a result. Next to its similarity to a thread
+resp. fiber it is also similar to a future or a promise. It provides access
+to its (future) result and offers the ability to shortcut its execution by
+manually injecting a result. Once the evaluation has a result it is *concluded*.
+
+```ruby
+# This is the root evaluation
+
+concurrently do
+  # This is a concurrent evaluation
+end
+
+concurrently do
+  # This is another concurrent evaluation
+end
+```
+
+
+## Concurrent Evaluation of Code
+
+Evaluating a piece of code concurrently involves three distinct phases:
 
-## Concurrent Procs
+                   1      2      3
+    evaluation0 ---+-------------+--->
+                   |             |
+    evaluation1    `--+-----+----´
+                      |     |
+                      t     io
 
-The [concurrent proc][Concurrently::Proc] is Concurrently's concurrency
-primitive. It looks and feels just like a regular proc. In fact,
-[Concurrently::Proc][] inherits from `Proc`.
+1. Invocation: evaluation0 kicks off evaluation1 to process the code in. It
+   does it asynchronously by not waiting for evaluation1 to finish.
+2. Computation: evaluation0 and evaluation1 run independently from each
+   other. evaluation1 synchronizes itself with other events (e.g. with time or
+   I/O).
+3. Synchronization: If evaluation0 is interested in the result of evaluation1
+   it has to wait for it. This synchronizes evaluation1 with evaluation0 again.
+   If evaluation1 has not finished yet evaluation0 blocks until it has.
 
-Concurrent procs are created with [Kernel#concurrent_proc][]:
+Every tool Concurrently offers is linked to one of these phases.
+
+
+### Invocation
+
+To start evaluating code concurrently use [Kernel#concurrently][]:
 
 ```ruby
-concurrent_proc do
+evaluation = concurrently do
   # code to run concurrently
 end
 ```
 
-Concurrent procs can be used the same way regular procs are. For example, they
-can be passed around or called multiple times with different arguments.
-    
-[Kernel#concurrently] is a shortcut for [Concurrently::Proc#call_and_forget][]:
-    
+It returns immediately with a handle to the started evaluation. The evaluation
+will be processed in the background.
+
+[Kernel#concurrently][] is actually a shortcut for
+
 ```ruby
-concurrently do
+evaluation = concurrent_proc do
   # code to run concurrently
-end
+end.call_detached
+```
+
+In general, you do not need to work with concurrent procs directly. Just use
+[Kernel#concurrently][]. But concurrent procs give you a finer control over
+how the code is evaluated. This comes in handy for optimizing performance.
 
-# is equivalent to:
 
-concurrent_proc do
+#### Concurrent Procs
+
+The [concurrent proc][Concurrently::Proc] looks and feels just like a regular
+proc. In fact, [Concurrently::Proc][] inherits from `Proc`. It is created with
+[Kernel#concurrent_proc][]:
+
+```ruby
+conproc = concurrent_proc do
   # code to run concurrently
-end.call_and_forget
+end
 ```
 
-### Calling Concurrent Procs
+Concurrent procs can be used the same way regular procs are. For example, they
+can be passed around or called multiple times with different arguments.
 
-A concurrent proc has four methods to call it.
+When called a concurrent proc kicks of an evaluation of its code. A concurrent
+proc has four methods to call it. Depending on which method is used the code
+is evaluated slightly differently.
 
-The first two evaluate the concurrent proc immediately in the foreground:
+The first two methods evaluate the concurrent proc immediately in the
+foreground:
 
-* [Concurrently::Proc#call][] blocks the (root or proc) evaluation it has been
-  called from until its own evaluation is concluded. Then it returns the
-  result. This behaves just like `Proc#call`.
-* [Concurrently::Proc#call_nonblock][] will not block the (root or proc)
-  evaluation it has been called from if it needs to wait. Instead, it
-  immediately returns its [evaluation][Concurrently::Proc::Evaluation]. If it
-  can be evaluated without waiting it returns the result.
+* [Concurrently::Proc#call][] blocks the evaluation it has been called from
+  until its own evaluation is concluded. Then it returns the result. This
+  behaves just like `Proc#call`.
+* [Concurrently::Proc#call_nonblock][] will not block the evaluation it has
+  been called from if it needs to wait. Instead, it immediately returns its 
+  own [evaluation][Concurrently::Proc::Evaluation]. If it can be evaluated
+  without waiting it returns the result.
 
 The other two schedule the concurrent proc to be run in the background. The
 evaluation is not started right away but is deferred until the the next
@@ -68,15 +127,30 @@ iteration of the event loop:
 * [Concurrently::Proc#call_and_forget][] does not give access to the evaluation
     and returns `nil`.
 
+The different methods to call a concurrent proc have an impact on the execution
+speed. In general, [Concurrently::Proc#call_detached][] represents a good
+middle ground between ease of use and performance. For an in-depth analysis of
+the performance implications of each call method have a look at the
+[performance documentation][performance]. It offers a guide what to use if
+every cpu cycle counts.
+
+
+### Computation
+
+In the computation phase the evaluation works through its code. While doing so
+it can synchronize itself with different events.
 
-## Timing Code
+All synchronization methods are named `await_*`. As usual, there is an exception
+to the rule: Waiting an amount of time is done with [Kernel#wait][].
 
-To defer the current evaluation for a fixed time use [Kernel#wait][].
+#### Synchronization with Time
+
+To defer the current evaluation for a fixed amount of time use [Kernel#wait][].
 
 * Doing something after X seconds:
     
     ```ruby
-    concurrent_proc do
+    concurrently do
       wait X
       do_it!
     end
@@ -85,7 +159,7 @@ To defer the current evaluation for a fixed time use [Kernel#wait][].
 * Doing something every X seconds. This is a timer:
     
     ```ruby
-    concurrent_proc do
+    concurrently do
       loop do
         wait X
         do_it!
@@ -96,7 +170,7 @@ To defer the current evaluation for a fixed time use [Kernel#wait][].
 * Doing something after X seconds, every Y seconds, Z times:
     
     ```ruby
-    concurrent_proc do
+    concurrently do
       wait X
       Z.times do
         do_it!
@@ -105,33 +179,33 @@ To defer the current evaluation for a fixed time use [Kernel#wait][].
     end
     ```
 
+* Doing something at a given point in time:
 
-## Handling I/O
+    ```ruby
+    concurrently do
+      time = Time.new(2042,7,10, 16,13,26) # 10 July 2042, 16:13:26
+      wait (time-Time.now).to_f
+      do_it!
+    end
+    ```
 
-Readiness of I/O is awaited with [IO#await_readable][] and [IO#await_writable][].
-To read and write from an IO concurrently you can use [IO#concurrently_read][]
-and [IO#concurrently_write][].
+#### Synchronization with I/O
+
+To read and write from an IO and wait until the operation is complete without
+blocking other evaluations use [IO#await_read][] and [IO#await_written][].
 
 ```ruby
 r,w = IO.pipe
 
 concurrently do
   wait 1
-  w.concurrently_write "Continue!"
-end
-
-concurrently do
-  # This runs while r awaits readability.
+  w.await_written "Continue!"
 end
 
-concurrently do
-  # This runs while r awaits readability.
-end
-
-# Read from r. It will take one second until there is input.
-message = r.concurrently_read 1024
 
-puts message # prints "Continue!"
+# Read from r. It will take one second until there is input because r must
+# wait until the string has been written to w.
+r.await_read 1024 # prints "Continue!"
 
 r.close
 w.close
@@ -157,23 +231,69 @@ end
 ```
 
 
-## Flow of Control
+#### Synchronization with Results of Evaluations
+
+Results of other evaluations can be waited for with
+[Concurrently::Proc::Evaluation#await_result][]:
+
+```ruby
+mailbox = concurrently do
+  wait 1
+  'message'
+end
+
+forwarder = concurrently do
+  "FW: #{mailbox.await_result}"
+end
+
+# It will take one second until there is a message in the mailbox
+puts forwarder.await_result # prints "FW: message"
+```
+
+To wait for the fastest in a list of evaluations use
+[Kernel#await_fastest][]:
+
+```ruby
+mailbox1 = concurrently do
+  wait 1
+  'slow message'
+end
+
+mailbox2 = concurrently do
+  wait 0.5
+  'fast message'
+end
+
+mailbox = await_fastest(mailbox1, mailbox2)
+mailbox.await_result # => "fast message"
+```
+
+
+### Synchronization
+
+Synchronizing the invoking evaluation with the result of the invoked one is
+done as described in the section about [synchronizing results of evaluations]
+(#Synchronization_with_Results_of_Evaluations).
+
+
+## About the Event Loop
 
 To understand when code is run (and when it is not) it is necessary to know
 a little bit more about the way Concurrently works.
 
-Concurrently lets every (real) thread run an [event loop][Concurrently::EventLoop].
-These event loops are responsible for watching IOs and scheduling evaluations
-of concurrent procs. Evaluations are scheduled by putting them into a run queue
-ordered by the time they are supposed to run. The run queue is then worked off
-sequentially. If two evaluations are scheduled to run at the same time the
+Concurrently lets every thread run an [event loop][Concurrently::EventLoop].
+These event loops work silently in the background and are responsible for
+watching IOs and scheduling evaluations. Evaluations are scheduled by putting
+them into a run queue ordered by the time they are supposed to run. The run
+queue is then worked off sequentially up to the point corresponding to the
+current time. If two evaluations are scheduled to run at the same time the
 evaluation scheduled first is run first.
 
 Event loops *do not* run parallel to your application's code at the exact same
 time (e.g. on another cpu core). Instead, your code yields to them if it
 waits for something: **The event loop is (and only is) entered if your code
-calls `#wait` or one of the `#await_*` methods.** Later, when your code can
-be resumed the event loop schedules the corresponding evaluation to run again.
+calls one of the synchronization methods.** Later, when your code can be
+resumed the event loop schedules the corresponding evaluation to run again.
 
 Keep in mind, that an event loop **must never be interrupted, blocked or
 overloaded.** A healthy event loop is one that can respond to new events
@@ -317,6 +437,9 @@ Keep in mind, that to focus on the use of Concurrently the example does not
 take error handling for I/O, properly closing all connections and other details
 into account.
 
+[README]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/file/README.md
+[API documentation]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/index
+[performance]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/file/guides/Performance.md
 [Concurrently::Evaluation]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/Evaluation
 [Concurrently::Proc]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/Proc
 [Concurrently::Proc#call]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/Proc#call-instance_method
@@ -324,12 +447,14 @@ into account.
 [Concurrently::Proc#call_detached]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/Proc#call_detached-instance_method
 [Concurrently::Proc#call_and_forget]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/Proc#call_and_forget-instance_method
 [Concurrently::Proc::Evaluation]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/Proc/Evaluation
+[Concurrently::Proc::Evaluation#await_result]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/Proc/Evaluation#await_result-instance_method
 [Concurrently::EventLoop]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Concurrently/EventLoop
 [Kernel#concurrent_proc]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Kernel#concurrent_proc-instance_method
 [Kernel#concurrently]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Kernel#concurrently-instance_method
 [Kernel#wait]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Kernel#wait-instance_method
+[Kernel#await_fastest]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/Kernel#await_fastest-instance_method
 [IO#await_readable]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#await_readable-instance_method
 [IO#await_writable]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#await_writable-instance_method
-[IO#concurrently_read]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#concurrently_read-instance_method
-[IO#concurrently_write]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#concurrently_write-instance_method
+[IO#await_read]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#await_read-instance_method
+[IO#await_written]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/IO#await_written-instance_method
 [Troubleshooting]: http://www.rubydoc.info/github/christopheraue/m-ruby-concurrently/file/guides/Troubleshooting.md