polyphony 0.20 → 0.21

data/docs/getting-started/tutorial.md

@@ -1,4 +1,137 @@
 # Tutorial
 
+## Building a Simple Echo Server with Polyphony
 
+In order to demonstrate how to use Polyphony, let's write an echo server, which
+accepts TCP connections and sends back whatever it receives from the client.
 
+We'll start by opening a server socket:
+
+```ruby
+require 'polyphony'
+
+server = TCPServer.open('127.0.0.1', 1234)
+puts 'Echoing on port 1234...'
+```
+
+Next, we'll add a loop accepting connections:
+
+```ruby
+while (client = server.accept)
+  handle_client(client)
+end
+```
+
+The `handle_client` method is almost trivial:
+
+```ruby
+def handle_client(client)
+  while (data = client.gets)
+    client.write('you said: ', data.chomp, "!\n")
+  end
+rescue Errno::ECONNRESET
+  puts 'Connection reset by client'
+end
+```
+
+### Adding Concurrency
+
+Up until now, we did nothing about concurrency. In fact, our code will not be
+able to handle more than one client at a time, because the accept loop cannot
+continue to run until the call to `#handle_client` returns, and that will not
+happen as long as the read loop is not done.
+
+Fortunately, Polyphony makes it super easy to do more than one thing at once.
+Let's spin up a separate coprocess for each client:
+
+```ruby
+while (client = server.accept)
+  spin { handle_client(client) }
+end
+```
+
+Now, our little program can handle virtually thousands of clients, all with a
+little sprinkling of `spin`. Let's discuss how this works. The `Kernel#spin`
+method starts a new coprocess, a separate context of execution based on [Ruby
+fibers](https://ruby-doc.org/core-2.6.5/Fiber.html). A coprocess may be
+arbitrarily suspended and resumed, and Polyphony takes advantage of this fact
+to implement a concurrent execution environment without the use of threads.
+
+The call to `server.accept` suspends the *root coprocess* until a connection is
+made, allowing other coprocesses to continue running. Likewise, the call to
+`client.gets` suspends the *client's coprocess* until incoming data becomes
+available. All this is handled automatically by Polyphony, and the only hint
+that our program is concurrent is that innocent call to `spin`.
+
+Let's consider the advantage of the Polyphony approach:
+
+- We didn't need to create custom handler classes with callbacks.
+- We didn't need to use custom classes or APIs for our networking code.
+- Our code is terse, easy to read and - most importantly - expresses the order of events clearly and without being split across callbacks.
+- We have a server that can scale to thousands of clients without breaking a sweat.
+
+## Handling Inactive Connections
+
+Now that we have a working concurrent echo server, let's add some bells and
+whistles. First of all, let's get rid of clients that are not active. We'll do
+this by using a Polyphony construct called a cancel scope. Cancel Scope define
+an execution context that can cancel any operation ocurring within its scope:
+
+```ruby
+def handle_client(client)
+  Polyphony::CancelScope.new(timeout: 10) do |scope|
+    while (data = client.gets)
+      scope.reset_timeout
+      client.write('you said: ', data.chomp, "!\n")
+    end
+  end
+rescue Errno::ECONNRESET
+  puts 'Connection reset by client'
+ensure
+  client.close
+end
+```
+
+The cancel scope is initialized with a timeout of 10 seconds. Any blocking
+operation ocurring within the cancel scope will be interrupted once 10 seconds
+have elapsed. In order to keep the connection alive while the client is active,
+we call `scope.reset_timeout` each time data is received from the client, and
+thus reset the cancel scope timer.
+
+In addition, we use an `ensure` block to make sure the client connection is
+closed, whether or not it was interrupted by the cancel scope timer. The habit
+of always cleaning up using `ensure` in the face of interruptions is a
+fundamental element of using Polyphony. It makes your code robust, even in a
+highly concurrent execution environment.
+
+Here's the complete source code for our Polyphony-based echo server:
+
+```ruby
+require 'polyphony/auto_run'
+
+server = TCPServer.open('127.0.0.1', 1234)
+puts 'Echoing on port 1234...'
+
+def handle_client(client)
+  Polyphony::CancelScope.new(timeout: 10) do |scope|
+    while (data = client.gets)
+      scope.reset_timeout
+      client.write('you said: ', data.chomp, "!\n")
+    end
+  end
+rescue Errno::ECONNRESET
+  puts 'Connection reset by client'
+ensure
+  client.close
+end
+
+while (client = server.accept)
+  spin { handle_client(client) }
+end
+```
+
+## Learning More
+
+Polyphony is still new, and the present documentation is far from being
+complete. For more information read the [technical overview](technical-overview/concurrency.md)
+or look at the [included examples](#).

data/docs/summary.md

@@ -1,12 +1,46 @@
 # Table of contents
 
-* [Introduction](../README.md)
+* [Polyphony - Easy Concurrency for Ruby](../README.md)
 
 ## Getting Started
 
-* [Installing](getting-started/getting-started.md)
+* [Installing](getting-started/installing.md)
 * [Tutorial](getting-started/tutorial.md)
 
 ## Technical overview
 
-* [Error handling](technical-overview/error-handling.md)
+* [Design Principles](technical-overview/design-principles.md)
+* [Concurrency the Easy Way](technical-overview/concurrency.md)
+* [How Fibers are Scheduled](technical-overview/fiber-scheduling.md)
+* [Exception Handling](technical-overview/exception-handling.md)
+* [Frequently Asked Questions](technical-overview/faq.md)
+
+## Using Polyphony
+
+* [Coprocesses](#)
+* [Supervisors](#)
+* [Cancel Scopes](#)
+* [Throttlers](#)
+* [Resource Pools](#)
+* [Synchronisation](#)
+* [Web Server](user-guide/web-server.md)
+* [Websocket Server](#)
+* [Reactor API](#)
+
+## API Reference
+
+* [Polyphony::CancelScope](#)
+* [Polyphony::Coprocess](#)
+* [Gyro](#)
+* [Gyro::Async](#)
+* [Gyro::Child](#)
+* [Gyro::IO](#)
+* [Gyro::Timer](#)
+* [Kernel](#)
+* [Polyphony](#)
+* [Polyphony::Mutex](#)
+* [Polyphony::Pulser](#)
+* [Polyphony::ResourcePool](#)
+* [Polyphony::Throttler](#)
+
+## [Contributing to Polyphony](contributing.md)

data/docs/technical-overview/concurrency.md

@@ -0,0 +1,47 @@
+# Concurrency the Easy Way
+
+Concurrency is a major consideration for modern programmers. Applications and digital platforms are nowadays expected to do multiple things at once: serve multiple clients, process multiple background jobs, talk to multiple external services. Concurrency is the property of our programming environment allowing us to schedule and control multiple ongoing operations.
+
+Traditionally, concurrency has been achieved by using multiple processes or threads. Both approaches have proven problematic. Processes consume relatively a lot of memory, and are relatively difficult to coordinate. Threads consume less memory than processes and make it difficult to synchronize access to shared resources, often leading to race conditions and memory corruption. Using threads often necessitates either using special-purpose thread-safe data structures, or otherwise protecting shared resource access using mutexes and critical sections. In addition, dynamic languages such as Ruby and Python will synchronize multiple threads using a global interpreter lock, which means thread execution cannot be parallelized. Furthermore, the amount of threads and processes on a single system is relatively limited, to the order of several hundreds or a few thousand at most.
+
+Polyphony offers a third way to write concurrent programs, by using a Ruby construct called [fibers](https://ruby-doc.org/core-2.6.5/Fiber.html). Fibers, based on the idea of [coroutines](https://en.wikipedia.org/wiki/Coroutine), provide a way to run a computation that can be suspended and resumed at any moment. For example, a computation waiting for a reply from a database can suspend itself, transferring control to another ongoing computation, and be resumed once the database has sent back its reply. Meanwhile, another computation is started that opens a socket to a remote service, and then suspends itself, waiting for the connection to be established.
+
+This form of concurrency, called cooperative concurrency \(in contrast to pre-emptive concurrency, like threads and processes\), offers many advantages, especially for applications that are [I/O bound](https://en.wikipedia.org/wiki/I/O_bound). Fibers are very lightweight \(starting at about 20KB\), can be context-switched faster than threads or processes, and literally millions of them can be created on a single system - the only limiting factor is available memory.
+
+Polyphony takes Ruby's fibers and adds a way to schedule and switch between fibers automatically whenever a blocking operation is started, such as waiting for a TCP connection to be established, or waiting for an I/O object to be readable, or waiting for a timer to elapse. In addition, Polyphony patches the stock Ruby classes to support its concurrency model, letting developers use all of Ruby's stdlib, for example `Net::HTTP` and `Mail` while reaping the benefits of lightweight, highly performant, fiber-based concurrency.
+
+Writing concurrent applications using Polyphony's fiber-based concurrency model offers a significant performance advantage. Computational tasks can be broken down into many fine-grained concurrent operations that cost very little in memory and context-switching time. More importantly, this concurrency model lets developers express their ideas in a sequential manner, leading to source code that is easy to read and reason about.
+
+## Coprocesses - Polyphony's basic unit of concurrency
+
+While stock Ruby fibers can be used with Polyphony without any problem, the API they provide is very basic, and necessitates writing quite a bit of boilerplate code whenever they need to be synchronized, interrupted or otherwise controlled. For this reason, Polyphony provides entities that encapsulate fibers and provide a richer API, making it easier to compose concurrent applications employing fibers.
+
+A coprocess can be thought of as a fiber with enhanced powers. It makes sure any exception raised while it's running is [handled correctly](exception-handling.md). It can be interrupted or `await`ed \(just like `Thread#join`\). It provides methods for controlling its execution. Moreover, coprocesses can pass messages between themselves, turning them into autonomous actors in a fine-grained concurrent environment.
+
+## Higher-Order Concurrency Constructs
+
+Polyphony also provides several methods and constructs for controlling multiple coprocesses. Methods like `cancel_after` and `move_on_after` allow interrupting a coprocess that's blocking on any arbitrary operation.
+
+Cancel scopes \(borrowed from the brilliant Python library [Trio](https://trio.readthedocs.io/en/stable/)\) allows cancelling ongoing operations for any reason with more control over cancelling behaviour.
+
+Supervisors allow controlling multiple coprocesses. They offer enhanced exception handling and can be nested to create complex supervision trees ala [Erlang](https://adoptingerlang.org/docs/development/supervision_trees/).
+
+Some other constructs offered by Polyphony:
+
+* `Mutex` - a mutex used to synchronize access to a single shared resource.
+* `ResourcePool` - used for synchronizing access to a limited amount of shared 
+
+  resources, for example a pool of database connections.
+
+* `Throttler` - used for throttling repeating operations, for example throttling
+
+  access to a shared resource, or throttling incoming requests.
+
+## A Compelling Concurrency Solution for Ruby
+
+> The goal of Ruby is to make programmers happy.
+
+— Yukihiro “Matz” Matsumoto
+
+Polyphony's goal is to make programmers even happier by offering them an easy way to write concurrent applications in Ruby. Polyphony aims to show that Ruby can be used for developing sufficiently high-performance applications, while offering all the advantages of Ruby, with source code that is easy to read and understand.
+

data/docs/technical-overview/design-principles.md

@@ -0,0 +1,112 @@
+# Design Principles
+
+Polyphony was created in order to enable creating high-performance concurrent
+applications in Ruby, by utilizing Ruby fibers together with the
+[libev](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod) event reactor
+library. Polyphony's design is based on the following principles:
+
+- Polyphony's concurrency model should feel "baked-in". The API should allow
+  concurrency with minimal effort. Polyphny should allow creating small
+  concurrent programs with as little boilerplate code as possible. There
+  should be no calls to initialize the event reactor, or other ceremonial code:
+
+  ```ruby
+  require 'polyphony/auto_run'
+
+  10.times {
+    # start 10 coprocesses, each sleeping for 1 second
+    spin { sleep 1 }
+  }
+
+  puts 'going to sleep now'
+  ```
+
+- Blocking operations should yield to the reactor without any decoration or
+  wrapper APIs. This means no `async/await` notation, and no built-in concept of
+  deferred computation.
+
+  ```ruby
+  # in Polyphony, I/O ops block the current fiber, but implicitly yield to other
+  # concurrent coprocesses:
+  clients.each { |client|
+    spin { client.puts 'Elvis has left the chatroom' }
+  }
+  ```
+
+- Concurrency primitives should be accessible using idiomatic Ruby techniques
+  (blocks, method chaining...) and should feel as much as possible "part of the
+  language". The resulting API is based more on methods and less on classes,
+  for example `spin` or `move_on_after`, leading to a coding style that is both
+  more compact and more legible:
+
+  ```ruby
+  coprocess = spin {
+    move_on_after(3) {
+      do_something_slow
+    }
+  }
+  ```
+- Polyphony should embrace Ruby's standard `raise/rescue/ensure` exception
+  handling mechanism:
+
+  ```ruby
+  cancel_after(0.5) do
+    puts 'going to sleep'
+    sleep 1
+    # this will not be printed
+    puts 'wokeup'
+  ensure
+    # this will be printed
+    puts 'done sleeping'
+  end
+  ```
+
+- Concurrency primitives should allow creating higher-order concurrent 
+  constructs through composition. This is done primarily through supervisors and
+  cancel scopes:
+
+  ```ruby
+  # wait for multiple coprocesses
+  supervise { |s|
+    clients.each { |client|
+      s.spin { client.puts 'Elvis has left the chatroom' }
+    }
+  }
+  ```
+
+- The internal reactor design should embrace fibers rather than be based on
+  invoking callbacks. The internal design of most reactor libraries is based on
+  callbacks. The design for Polyphony should center on suspending and resuming
+  fibers:
+
+  ```ruby
+  # psuedo-code for Gyro::Timer, the internal timer class
+  def Gyro::Timer.await
+    @fiber = Fiber.current
+    # the libev event reactor uses callbacks for handling events, Polyphony uses
+    # callbacks for switching between fibers
+    EV.start_timer(@interval) { @fiber.transfer }
+  end
+  ```
+
+- Use of extensive monkey patching of Ruby core modules and classes such as
+  `Kernel`, `Fiber`, `IO` and `Timeout`. This allows porting over non-Polyphony
+  code, as well as using a larger part of stdlib in a concurrent manner, without
+  having to use custom non-standard network classes or other glue code.
+
+  ```ruby
+  require 'polyphony'
+
+  # use TCPServer from Ruby's stdlib
+  server = TCPServer.open('127.0.0.1', 1234)
+  while (client = server.accept)
+    spin do
+      while (data = client.gets)
+        client.write('you said: ', data.chomp, "!\n")
+      end
+    end
+  end
+  ```
+
+- Development of techniques and tools for coverting callback-based APIs to
+  fiber-based ones.

data/docs/technical-overview/exception-handling.md

@@ -1,14 +1,9 @@
-# Exception Handling in a Multi-Fiber Environment
+# Exception Handling
 
-Ruby employs a pretty robust exception handling mechanism. An raised exception
-will bubble up the call stack until a suitable exception handler is found, based
-on the exception's class. In addition, the exception will include a stack trace
-showing the execution path from the exception's locus back to the program's
-entry point. Unfortunately, when exceptions are raised while switching between
-fibers, stack traces will only include partial information. Here's a simple
-demonstration:
+Ruby employs a pretty robust exception handling mechanism. An raised exception will bubble up the call stack until a suitable exception handler is found, based on the exception's class. In addition, the exception will include a stack trace showing the execution path from the exception's locus back to the program's entry point. Unfortunately, when exceptions are raised while switching between fibers, stack traces will only include partial information. Here's a simple demonstration:
+
+_fiber\_exception.rb_
 
-*fiber_exception.rb*
 ```ruby
 require 'fiber'
 
@@ -27,19 +22,15 @@ f.transfer
 
 Running the above program will give us:
 
-```
+```text
 Traceback (most recent call last):
         1: from fiber_exception.rb:9:in `block (2 levels) in <main>'
 fiber_exception.rb:4:in `fail!': foobar (RuntimeError)
 ```
 
-So, the stack trace includes two frames: the exception's locus on line 4 and the
-call site at line 9. But we have no information on how we got to line 9. Let's
-imagine if we had more complete information about the sequence of execution. In
-fact, what is missing is information about how the different fibers were
-created. If we had that, our stack trace would have looked something like this:
+So, the stack trace includes two frames: the exception's locus on line 4 and the call site at line 9. But we have no information on how we got to line 9. Let's imagine if we had more complete information about the sequence of execution. In fact, what is missing is information about how the different fibers were created. If we had that, our stack trace would have looked something like this:
 
-```
+```text
 Traceback (most recent call last):
         4: from fiber_exception.rb:13:in `<main>'
         3: from fiber_exception.rb:7:in `Fiber.new'
@@ -48,19 +39,9 @@ Traceback (most recent call last):
 fiber_exception.rb:4:in `fail!': foobar (RuntimeError)
 ```
 
-In order to achieve this, Polyphony patches `Fiber.new` to keep track of the
-call stack at the moment the fiber was created, as well as the fiber from which
-the call happened. In addition, Polyphony patches `Exception#backtrace` in order
-to synthesize a complete stack trace based on the call stack information stored
-for the current fiber. This is done recursively through the chain of fibers
-leading up to the current location. What we end up with is a record of the
-entire sequence of (possibly intermittent) execution leading up to the point
-where the exception was raised.
+In order to achieve this, Polyphony patches `Fiber.new` to keep track of the call stack at the moment the fiber was created, as well as the fiber from which the call happened. In addition, Polyphony patches `Exception#backtrace` in order to synthesize a complete stack trace based on the call stack information stored for the current fiber. This is done recursively through the chain of fibers leading up to the current location. What we end up with is a record of the entire sequence of \(possibly intermittent\) execution leading up to the point where the exception was raised.
 
-In addition, the backtrace is sanitized to remove stack frames originating from
-the Polyphony code itself, which hides away the Polyphony plumbing and lets
-developers concentrate on their own code. The sanitizing of exception backtraces
-can be disabled by setting the `Exception.__disable_sanitized_backtrace__` flag:
+In addition, the backtrace is sanitized to remove stack frames originating from the Polyphony code itself, which hides away the Polyphony plumbing and lets developers concentrate on their own code. The sanitizing of exception backtraces can be disabled by setting the `Exception.__disable_sanitized_backtrace__` flag:
 
 ```ruby
 Exception.__disable_sanitized_backtrace__ = true
@@ -69,10 +50,7 @@ Exception.__disable_sanitized_backtrace__ = true
 
 ## Cleaning up after exceptions
 
-A major issue when handling exceptions is cleaning up - freeing up resources
-that have been allocated, cancelling ongoing operations, etc. Polyphony allows
-using the normal `ensure` statement for cleaning up. Have a look at Polyphony's
-implementation of `Kernel#sleep`:
+A major issue when handling exceptions is cleaning up - freeing up resources that have been allocated, cancelling ongoing operations, etc. Polyphony allows using the normal `ensure` statement for cleaning up. Have a look at Polyphony's implementation of `Kernel#sleep`:
 
 ```ruby
 def sleep(duration)
@@ -83,12 +61,27 @@ ensure
 end
 ```
 
-This method creates a one-shot timer with the given duration and then suspends
-the current fiber, waiting for the timer to fire and then resume the fiber.
-While the awaiting fiber is suspended, other operations might be going on, which
-might interrupt the `sleep` operation by scheduling the awaiting fiber with an
-exception, for example a `MoveOn` or a `Cancel` exception. For this reason, we
-need to *ensure* that the timer will be stopped, regardless of whether it has
-fired or not. We call `timer.stop` inside an ensure block, thus ensuring that
-the timer will have stopped once the awaiting fiber has resumed, even if it has
-not fired.
+This method creates a one-shot timer with the given duration and then suspends the current fiber, waiting for the timer to fire and then resume the fiber. While the awaiting fiber is suspended, other operations might be going on, which might interrupt the `sleep` operation by scheduling the awaiting fiber with an exception, for example a `MoveOn` or a `Cancel` exception. For this reason, we need to _ensure_ that the timer will be stopped, regardless of whether it has fired or not. We call `timer.stop` inside an ensure block, thus ensuring that the timer will have stopped once the awaiting fiber has resumed, even if it has not fired.
+
+## Bubbling Up - A Robust Solution for Uncaught Exceptions
+
+One of the "annoying" things about exceptions is that for them to be useful, you have to intercept them \(using `rescue`\). If you forget to do that, you'll end up with uncaught exceptions that can wreak havoc. For example, by default a Ruby `Thread` in which an exception was raised without being caught, will simply terminate with the exception silently swallowed.
+
+To prevent the same from happening with fibers, Polyphony provides a mechanism that lets uncaught exceptions bubble up through the chain of calling fibers. Let's discuss the following example:
+
+```ruby
+require 'polyphony'
+
+spin do
+  spin do
+    spin do
+      spin do
+        raise 'foo'
+      end.await
+    end.await
+  end.await
+end.await
+```
+
+In this example, there are four coprocesses, nested one within the other. An exception is raised in the inner most coprocess, and having no exception handler, will bubble up through the different enclosing coprocesses, until reaching the top-most level, that of the root fiber, at which point the exception will cause the program to halt and print an error message.
+

data/docs/technical-overview/extending.md

@@ -0,0 +1,80 @@
+# Extending Polyphony
+
+Polyphony was designed to ease the transition from blocking APIs and 
+callback-based API to non-blocking, fiber-based ones. It is important to
+understand that not all blocking calls can be easily converted into 
+non-blocking calls. That might be the case with Ruby gems based on C-extensions,
+such as database libraries. In that case, Polyphony's built-in
+[thread pool](#threadpool) might be used for offloading such blocking calls.
+
+### Adapting callback-based APIs
+
+Some of the most common patterns in Ruby APIs is the callback pattern, in which
+the API takes a block as a callback to be called upon completion of a task. One
+such example can be found in the excellent
+[http_parser.rb](https://github.com/tmm1/http_parser.rb/) gem, which is used by
+Polyphony itself to provide HTTP 1 functionality. The `HTTP:Parser` provides 
+multiple hooks, or callbacks, for being notified when an HTTP request is
+complete. The typical callback-based setup is as follows:
+
+```ruby
+require 'http/parser'
+@parser = Http::Parser.new
+
+def on_receive(data)
+  @parser < data
+end
+
+@parser.on_message_complete do |env|
+  process_request(env)
+end
+```
+
+A program using `http_parser.rb` in conjunction with Polyphony might do the
+following:
+
+```ruby
+require 'http/parser'
+require 'polyphony'
+
+def handle_client(client)
+  parser = Http::Parser.new
+  req = nil
+  parser.on_message_complete { |env| req = env }
+  loop do
+    parser << client.read
+    if req
+      handle_request(req)
+      req = nil
+    end
+  end
+end
+```
+
+Another possibility would be to monkey-patch `Http::Parser` in order to
+encapsulate the state of the request:
+
+```ruby
+class Http::Parser
+  def setup
+    self.on_message_complete = proc { @request_complete = true }
+  end
+
+  def parser(data)
+    self << data
+    return nil unless @request_complete
+
+    @request_complete = nil
+    self
+  end
+end
+
+def handle_client(client)
+  parser = Http::Parser.new
+  loop do
+    if req == parser.parse(client.read)
+      handle_request(req)
+    end
+  end
+end
+```

data/docs/technical-overview/faq.md

@@ -0,0 +1,74 @@
+# Frequently Asked Questions
+
+## Why not just use callbacks instead of fibers?
+
+It is true that reactor engines such as libev use callbacks to handle events. There's also programming platforms such as [node.js](https://nodejs.org/) that base their entire API on the callback pattern. [EventMachine](https://www.rubydoc.info/gems/eventmachine/1.2.7) is a popular reactor library for Ruby that uses callbacks for handling events.
+
+Using callbacks means splitting your application logic into disjunct pieces of code. Consider the following example:
+
+```ruby
+require 'eventmachine'
+
+module EchoServer
+  def post_init
+    puts '-- someone connected to the echo server!'
+  end
+
+  def receive_data data
+    send_data ">>>you sent: #{data}"
+    close_connection if data =~ /quit/i
+  end
+
+  def unbind
+    puts '-- someone disconnected from the echo server!'
+  end
+end
+
+# Note that this will block current thread.
+EventMachine.run {
+  EventMachine.start_server '127.0.0.1', 8081, EchoServer
+}
+```
+
+The client-handling code is split across three different callback methods. Compare this to the following equivalent using Polyphony:
+
+```ruby
+require 'polyphony/auto_run'
+
+server = TCPServer.open('127.0.0.1', 8081)
+while (client = server.accept)
+  spin do
+    puts '-- someone connected to the echo server!'
+    while (data = client.gets)
+      client << ">>>you sent: #{data}"
+      break if data =~ /quit/i
+    end
+  ensure
+    client.close
+    puts '-- someone disconnected from the echo server!'
+  end
+end
+```
+
+The Polyphony version is both more terse and explicit at the same time. It explicitly accepts connections on the server port, and the entire logic handling each client connection is contained in a single block. The order of the different actions - printing to the console, then echoing client messages, then finally closing the client connection and printing again to the console - is easy to grok. The echoing of client messages is also explicit: a simple loop waiting for a message, then responding to the client. In addition, we can use an `ensure` block to correctly cleanup even if exceptions are raised while handling the client.
+
+Using callbacks also makes it much more difficult to debug your program. when callbacks are used to handle events, the stack trace will necessarily start at the reactor, and thus lack any information about how the event came to be in the first place. Contrast this with Polyphony, where stack traces show the entire _sequence of events_ leading up to the present point in the code.
+
+In conclusion:
+
+* Callbacks cause the splitting of logic into disjunct chunks.
+* Callbacks do not provide a good error handling solution.
+* Callbacks often lead to code bloat.
+* Callbacks are harder to debug.
+
+## If callbacks suck, why not use promises?
+
+Promises have gained a lot of traction during the last few years as an  
+alternative to callbacks, above all in the Javascript community. While promises have been at a certain point considered for use in Polyphony, they were not found to offer enough of a benefit. Promises still cause split logic, are quite verbose and provide a non-native exception handling mechanism. In addition, they do not make it easier to debug your code.
+
+## Why is awaiting implicit? Why not use explicit async/await?
+
+Actually, async/await was contemplated while developing Polyphony, but at a certain point it was decided to abandon these methods / decorators in favor of a more implicit approach. The most crucial issue with async/await is that it prevents the use of anything from Ruby's stdlib. Any operation involving stdlib classes needs to be wrapped in boilerplate.
+
+Instead, we have decided to make blocking operations implicit and thus allow the use of common APIs such as `Kernel#sleep` or `IO.popen` in a transparent manner. After all, these APIs in their stock form block execution just as well.
+