diff --git a/README.md b/README.md
index 8b34b80..c47d913 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,22 @@ Promises in combination with generators are used to build coroutines, which allo
+## Motivation
+
+Traditionally, PHP has a synchronous execution flow, doing one thing at a time.
+If you query a database, you send the query and wait for the response from the database server in a blocking manner.
+Once you have the response, you can start doing the next thing.
+
+Instead of sitting there and doing nothing while waiting, we could already send the next database query, or do an HTTP call to an API.
+
+Making use of the time we usually spend on waiting for I/O can speed up the total execution time.
+The following diagram shows the execution flow with dependencies between the different tasks, once executed sequentially and once concurrently.
+
+
+
+Amp allows such concurrent I/O operations while keeping the cognitive load low by avoiding callbacks.
+Instead, the results of asynchronous operations can be awaited using `yield` resulting in code which is structured like traditional blocking I/O code while the actual execution flow is handled by Amp.
+
## Installation
This package can be installed as a [Composer](https://getcomposer.org/) dependency.
@@ -20,72 +36,51 @@ This package can be installed as a [Composer](https://getcomposer.org/) dependen
composer require amphp/amp
```
+This installs the basic building blocks for asynchronous applications in PHP.
+We offer a lot of repositories building on top of this repository, e.g.
+
+ - [`amphp/byte-stream`](https://github.com/amphp/byte-stream) providing a stream abstraction
+ - [`amphp/socket`](https://github.com/amphp/socket) providing a socket layer for UDP and TCP including TLS
+ - [`amphp/parallel`](https://github.com/amphp/parallel) providing parallel processing to utilize multiple CPU cores and offload blocking operations
+ - [`amphp/http-client`](https://github.com/amphp/http-client) providing an HTTP/1.1 and HTTP/2 client
+ - [`amphp/http-server`](https://github.com/amphp/http-server) providing an HTTP/1.1 and HTTP/2 application server
+ - [`amphp/mysql`](https://github.com/amphp/mysql) and [`amphp/postgres`](https://github.com/amphp/postgres) for non-blocking database access
+ - and [many more packages](https://github.com/amphp?type=source)
+
## Documentation
Documentation can be found on [amphp.org](https://amphp.org/) as well as in the [`./docs`](./docs) directory.
+Each packages has it's own `./docs` directory.
## Requirements
-- PHP 7.0+
+This package requires PHP 7.0 or later.
+Many of the other packages raised their requirement to PHP 7.1.
+No extensions required!
-##### Optional Extension Backends
+##### Optional Extensions
-Extensions are only needed if your app necessitates a high numbers of concurrent socket connections.
+Extensions are only needed if your app necessitates a high numbers of concurrent socket connections, usually this limit is configured up to 1024 file descriptors.
-- [ev](https://pecl.php.net/package/ev)
-- [event](https://pecl.php.net/package/event)
-- [php-uv](https://github.com/bwoebi/php-uv) (experimental fork)
+- [`ev`](https://pecl.php.net/package/ev)
+- [`event`](https://pecl.php.net/package/event)
+- [`uv`](https://github.com/bwoebi/php-uv)
## Examples
-This simple example uses our [Artax](https://amphp.org/artax/) HTTP client to fetch multiple HTTP resources concurrently.
-
-```php
-setOption(Amp\Artax\Client::OP_DISCARD_BODY, true);
-
- try {
- foreach ($uris as $uri) {
- $promises[$uri] = $client->request($uri);
- }
-
- $responses = yield $promises;
-
- foreach ($responses as $uri => $response) {
- print $uri . " - " . $response->getStatus() . $response->getReason() . PHP_EOL;
- }
- } catch (Amp\Artax\HttpException $error) {
- // If something goes wrong Amp will throw the exception where the promise was yielded.
- // The Client::request() method itself will never throw directly, but returns a promise.
- print $error->getMessage() . PHP_EOL;
- }
-});
-```
-
-Further examples can be found in the [`./examples`](./examples) directory of this repository as well as in the `./examples` directory of [our other libraries](https://github.com/amphp?utf8=%E2%9C%93&q=&type=public&language=php)
+Examples can be found in the [`./examples`](./examples) directory of this repository as well as in the `./examples` directory of [our other libraries](https://github.com/amphp?utf8=%E2%9C%93&q=&type=public&language=php).
## Versioning
`amphp/amp` follows the [semver](http://semver.org/) semantic versioning specification like all other `amphp` packages.
-| Version | Bug Fixes Until | Security Fixes Until |
-| ------- | --------------- | -------------------- |
-| 2.x | TBA | TBA |
-| 1.x | 2017-12-31 | 2018-12-31 |
+##### v2.x
+
+Supported. We don't have plans to release v3, yet.
+
+##### v1.x
+
+No longer supported. We stopped providing bug fixes 2017-12-31 and stopped providing security fixes 2018-12-31.
## Compatible Packages
@@ -93,7 +88,7 @@ Compatible packages should use the [`amphp`](https://github.com/search?utf8=%E2%
## Security
-If you discover any security related issues, please email [`bobwei9@hotmail.com`](mailto:bobwei9@hotmail.com) or [`me@kelunik.com`](mailto:me@kelunik.com) instead of using the issue tracker.
+If you discover any security related issues, please email [`me@kelunik.com`](mailto:me@kelunik.com) instead of using the issue tracker.
## License
diff --git a/docs/images/sequential-vs-concurrent.png b/docs/images/sequential-vs-concurrent.png
new file mode 100644
index 0000000..b9815a4
Binary files /dev/null and b/docs/images/sequential-vs-concurrent.png differ