From d1ef36fa1014ea5d81437b090df321285ec9b23b Mon Sep 17 00:00:00 2001
From: Niklas Keller <me@kelunik.com>
Date: Thu, 4 May 2017 12:23:54 +0200
Subject: [PATCH] Add basic coroutine docs, closes #90

---
 docs/coroutines/README.md    | 50 ++++++++++++++++++++++++++++++++++--
 docs/managing-concurrency.md | 49 -----------------------------------
 2 files changed, 48 insertions(+), 51 deletions(-)
 delete mode 100644 docs/managing-concurrency.md

diff --git a/docs/coroutines/README.md b/docs/coroutines/README.md
index 837ec4af..192fa359 100644
--- a/docs/coroutines/README.md
+++ b/docs/coroutines/README.md
@@ -1,3 +1,49 @@
-# Streams
+# Coroutines
 
-This is a documentation stub. Please help writing this documentation. See [#90](https://github.com/amphp/amp/issues/90).
+Coroutines are interruptible functions. In PHP they can be implemented using [generators](http://php.net/manual/en/language.generators.overview.php).
+
+While generators are usually used to implement simple iterators and yielding elements using the `yield` keyword, Amp uses `yield` as interruption points. When a coroutine yields a value, execution of the coroutine is temporarily interrupted, allowing other tasks to be run, such as I/O handlers, timers, or other coroutines.
+
+## Yield Behavior
+
+All yields must be one of the following three types:
+
+| Yieldable     | Description                                                                                                                                                                                                                      |
+| --------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Amp\Promise` | Any promise instance may be yielded and control will be returned to the coroutine once the promise resolves. If resolution fails the relevant exception is thrown into the generator and must be handled by the application or it will bubble up. If resolution succeeds the promise's resolved value is sent back into the generator. |
+| `React\Promise\PromiseInterface` | Same as `Amp\Promise`. Any React promise will automatically be adapted to an Amp promise. |
+| `array` | Yielding an array of promises combines them implicitly using `Amp\Promise\all()`. An array with elements not being promises will result in an `Amp\InvalidYieldError`. |
+
+## Example
+
+```php
+<?php
+
+use Amp\Loop;
+
+function asyncMultiply($x, $y): Amp\Promise {
+    // Use Amp\call to always return promise instead of a \Generator.
+    // Generators are an implementation detail that shouldn't be leaked to API consumers.
+    return Amp\call(function () use ($x, $y) {
+        yield new Amp\Delayed($millisecondsToPause = 100);
+        return $x * $y;        
+    });
+}
+
+Loop::run(function () {
+    try {
+        // Yield control until the generator resolves
+        // and return its eventual result.
+        $result = yield asyncMultiply(2, 21); // int(42)
+    } catch (Exception $e) {
+        // If promise resolution fails the exception is
+        // thrown back to us and we handle it as needed.
+    }
+});
+```
+
+Note that **no callbacks need to be registered** to consume promises and **errors can be handled with ordinary `catch` clauses**, which will bubble up to the calling context if uncaught in the same way exceptions bubble up in synchronous code.
+
+## Further Reading
+
+ * [Coroutine Helpers](./helpers.md)
diff --git a/docs/managing-concurrency.md b/docs/managing-concurrency.md
deleted file mode 100644
index 949611d7..00000000
--- a/docs/managing-concurrency.md
+++ /dev/null
@@ -1,49 +0,0 @@
-@TODO: Move remaining parts to coroutine docs once they exist.
-
-## Generators
-
-The addition of generators in PHP 5.5 trivializes synchronization and error handling in async contexts. The Amp event loop builds in coroutine support for all event loop callbacks so we can use the `yield` keyword to make async code feel synchronous. Let's look at a simple example executing inside the event loop run loop:
-
-```php
-<?php
-
-use Amp\Loop;
-
-function asyncMultiply($x, $y) {
-    yield new Amp\Delayed($millisecondsToPause = 100);
-    return $x * $y;
-}
-
-Loop::run(function () {
-    try {
-        // Yield control until the generator resolves
-        // and return its eventual result.
-        $result = yield from asyncMultiply(2, 21); // int(42)
-    } catch (Exception $e) {
-        // If promise resolution fails the exception is
-        // thrown back to us and we handle it as needed.
-    }
-});
-```
-
-As you can see in the above example there is no need for callbacks or `.then()` chaining. Instead,
-we're able to use `yield` statements to control program flow even when future computational results
-are still pending.
-
-> **NOTE**
->
-> Any time a generator yields an `Amp\Promise` there exists the possibility that the associated async operation(s) could fail. When this happens the appropriate exception is thrown back into the calling generator. Applications should generally wrap their promise yields in `try/catch` blocks as an error handling mechanism in this case.
-
-### Subgenerators
-
-As of PHP 7 you can use `yield from` to delegate a sub task to another generator. That generator will be embedded into the currently running generator.
-
-### Yield Behavior
-
-All yields must be one of the following three types:
-
-| Yieldable     | Description                                                                                                                                                                                                                      |
-| --------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `Amp\Promise` | Any promise instance may be yielded and control will be returned to the generator once the promise resolves. If resolution fails the relevant exception is thrown into the generator and must be handled by the application or it will bubble up. If resolution succeeds the promise's resolved value is sent back into the generator. |
-| `React\Promise\PromiseInterface` | Same as `Amp\Promise`. Any React promise will automatically be adapted to an Amp promise. |
-| `array` | Yielding an array of promises combines them implicitly using `Amp\all`. An array with elements not being promises will result in an `Amp\InvalidYieldError`. |