Merge pull request #8 from async-interop/metasplit

Extract meta info into a separate document

Author: kelunik

META.md

@@ -0,0 +1,27 @@
+# Awaitable
+
+This document describes a few design considerations, for the main specification, refer to [the README document](README.md).
+
+## Recommended usage of Awaitable
+
+We are explicitly _not_ providing a chainable method, thus we are also not recommending to chain them, but rather to use coroutines in form of generators inside application code.
+
+Coroutines solve the problem of the so-called callback hell very nicely and also allow proper usage of `try` / `catch`.
+
+## Choice of `when()`
+
+The specification proposes `when()` in order to only expose the most primitive common denominatior needed for interoperability, which is a simple callable to be executed after the resolution.
+
+If implementations wish to adhere to e.g. [Promises/A+ from Javascript](https://promisesaplus.com) (which had been implemented in many PHP Promise libraries at the time of writing this specification) or implement any other methods, they still may do so; `when()` however is the fundamental interoperable primitive every `Awaitable` is guaranteed to have.
+
+Additionally, coroutines do not use the returned `Promise` of a `then` callback, but returning a `Promise` is required by Promises/A+. Thus there's a lot of useless object creations when using Awaitables the recommended way, which isn't cheap and adds up. This conflicts with the goal of being as lightweight as possible.
+
+## Naming
+
+As we are not using a thenable, which is sometimes associated with the word `Promise`, we decided against using `Promise`.
+
+Thus, `Awaitable` was a logical choice, with [HHVM already having it](https://docs.hhvm.com/hack/reference/interface/HH.Awaitable/) and PHP possibly also being some day extended to natively support an `await` keyword.
+
+## Creation of Awaitables
+
+Awaitable creation and managing is out of scope of this specification, as managing never shall cross library boundaries and thus does not need to be interoperable at all; each library shall resolve the Awaitable it created itself.

README.md

@@ -6,22 +6,22 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
 interpreted as described in [RFC 2119][].
 
-An `Awaitable` represents the eventual result of an asynchronous operation. Interaction with an `Awaitable` happens through its `when` method, which registers a callback to receive either an `Awaitable`'s eventual value or the reason why the `Awaitable` has failed. They're basically the same as a `Promise` in JavaScript's [Promises/A+ specification]([Promises/A+](https://promisesaplus.com/)), but the interaction with them is different as the following paragraphs show.
+An `Awaitable` represents the eventual result of an asynchronous operation. Interaction with an `Awaitable` happens through its `when` method, which registers a callback to receive either an `Awaitable`'s eventual value or the reason why the `Awaitable` has failed.
 
-This specification defines the absolute minimums for interoperable coroutines, which can be implemented in PHP using generators. Further methods like a `watch` method for progress updates or `then` for chainability are out of scope of this specification. The name `Awaitable` works well, especially when PHP is extended to support `await`, and is also [already used in HHVM](https://docs.hhvm.com/hack/reference/interface/HH.Awaitable/).
+`Awaitable` is the fundamental primitive in asynchronous programming. It should be as lightweight as possible, as any cost adds up significantly.
 
-`Awaitable` is the fundamental primitive in asynchronous programming. It should be as lightweight as possible, as any cost adds up significantly. The existing Promises/A+ specification conflicts with the goal of lightweight primitives. This specification uses `when`, so existing implementations can continue to provide `then` for chainability.
-
-Coroutines should be the preferred way of writing asynchronous code, as it allows the use of `try` / `catch` and doesn't result in a so-called callback hell. Coroutines do not use the returned `Promise` of a `then` callback, but returning a `Promise` is required by Promises/A+. Thus there's a lot of useless object creations, which aren't cheap and add up.
+This specification defines the absolute minimums for interoperable coroutines, which can be implemented in PHP using generators.
 
 This specification does not deal with how to create, succeed or fail `Awaitable`s, as only the consumption of `Awaitable`s is required to be interoperable.
 
+For further design explanations and notes, please refer to [the meta document](META.md).
+
 ## Terminology
 
 1. _Awaitable_ is an object implementing `Interop\Async\Awaitable` and conforming to this specification.
-1. _Value_ is any legal PHP value (including `null`), except an instance of `Interop\Async\Awaitable`.
-1. _Error_ is any value that can be thrown using the `throw` statement.
-1. _Reason_ is an error indicating why an `Awaitable` has failed.
+2. _Value_ is any legal PHP value (including `null`), except an instance of `Interop\Async\Awaitable`.
+3. _Error_ is any value that can be thrown using the `throw` statement.
+4. _Reason_ is an error indicating why an `Awaitable` has failed.
 
 ## States