From 2090e918b10ab9b587949b1db44f0cbf23285955 Mon Sep 17 00:00:00 2001 From: Jan Sorgalla Date: Mon, 27 Mar 2017 08:47:38 +0200 Subject: [PATCH 1/2] Restructure and improve README * Separate into sections and add a TOC at the beginning * Add new sections for Install, Tests and License * Add paragraph to Usage emphasizing on recommended program structuring using a single loop instance --- README.md | 131 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 100 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index ab1f462f..6967450c 100644 --- a/README.md +++ b/README.md @@ -5,39 +5,20 @@ Event loop abstraction layer that libraries can use for evented I/O. -In order for async based libraries to be interoperable, they need to use the -same event loop. This component provides a common `LoopInterface` that any -library can target. This allows them to be used in the same loop, with one -single `run` call that is controlled by the user. - > The master branch contains the code for the upcoming 0.5 release. For the code of the current stable 0.4.x release, checkout the [0.4 branch](https://github.com/reactphp/event-loop/tree/0.4). -In addition to the interface there are some implementations provided: - -* `StreamSelectLoop`: This is the only implementation which works out of the - box with PHP. It does a simple `select` system call. It's not the most - performant of loops, but still does the job quite well. - -* `LibEventLoop`: This uses the `libevent` pecl extension. `libevent` itself - supports a number of system-specific backends (epoll, kqueue). - -* `LibEvLoop`: This uses the `libev` pecl extension - ([github](https://github.com/m4rw3r/php-libev)). It supports the same - backends as libevent. +**Table of Contents** -* `ExtEventLoop`: This uses the `event` pecl extension. It supports the same - backends as libevent. +* [Quickstart example](#quickstart-example) +* [Usage](#usage) +* [Loop implementations](#loop-implementations) +* [Install](#install) +* [Tests](#tests) +* [License](#license) -All of the loops support these features: - -* File descriptor polling -* One-off timers -* Periodic timers -* Deferred execution of callbacks - -## Usage +## Quickstart example Here is an async HTTP server built with just the event loop. @@ -46,6 +27,7 @@ $loop = React\EventLoop\Factory::create(); $server = stream_socket_server('tcp://127.0.0.1:8080'); stream_set_blocking($server, 0); + $loop->addReadStream($server, function ($server) use ($loop) { $conn = stream_socket_accept($server); $data = "HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nHi\n"; @@ -69,7 +51,94 @@ $loop->addPeriodicTimer(5, function () { $loop->run(); ``` -**Note:** The factory is just for convenience. It tries to pick the best -available implementation. Libraries `SHOULD` allow the user to inject an -instance of the loop. They `MAY` use the factory when the user did not supply -a loop. +## Usage + +In order for async based libraries to be interoperable, they need to use the +same event loop. This component provides a common `LoopInterface` that any +library can target. This allows them to be used in the same loop, with one +single `run()` call that is controlled by the user. + +```php +// [1] +$loop = React\EventLoop\Factory::create(); + +// [2] +$loop->addPeriodicTimer(1, function () { + echo "Tick\n"; +}); + +$stream = new React\Stream\ReadableResourceStream( + fopen('file.txt', 'r'), + $loop +); + +// [3] +$loop->run(); +``` + +1. The loop instance is created at the beginning of the program. A convenience + factory `React\EventLoop\Factory::create()` is provided by this library which + picks the best available [loop implementation](#loop-implementations). +2. The loop instance is used directly or passed to library and application code. + In this example, a periodic timer is registered with the event loop which + simply outputs `Tick` every second and a + [readable stream](https://github.com/reactphp/stream#readableresourcestream) + is created by using ReactPHP's + [stream component](https://github.com/reactphp/stream) for demonstration + purposes. +3. The loop is run with a single `$loop->run()` call at the end of the program. + +## Loop implementations + +In addition to the interface there are the following implementations provided: + +* `StreamSelectLoop`: This is the only implementation which works out of the + box with PHP. It does a simple `select` system call. It's not the most + performant of loops, but still does the job quite well. + +* `LibEventLoop`: This uses the `libevent` pecl extension. `libevent` itself + supports a number of system-specific backends (epoll, kqueue). + +* `LibEvLoop`: This uses the `libev` pecl extension + ([github](https://github.com/m4rw3r/php-libev)). It supports the same + backends as libevent. + +* `ExtEventLoop`: This uses the `event` pecl extension. It supports the same + backends as libevent. + +All of the loops support these features: + +* File descriptor polling +* One-off timers +* Periodic timers +* Deferred execution of callbacks + +## Install + +The recommended way to install this library is [through Composer](http://getcomposer.org). +[New to Composer?](http://getcomposer.org/doc/00-intro.md) + +This will install the latest supported version: + +```bash +$ composer require react/event-loop +``` + +## Tests + +To run the test suite, you first need to clone this repo and then install all +dependencies [through Composer](http://getcomposer.org): + +```bash +$ composer install +``` + +To run the test suite, go to the project root and run: + +```bash +$ php vendor/bin/phpunit +``` + +## License + +MIT, see [LICENSE file](LICENSE). From 49491cb4272de2a12afbb32224d4ee83aebb9ae2 Mon Sep 17 00:00:00 2001 From: Jan Sorgalla Date: Mon, 27 Mar 2017 14:41:57 +0200 Subject: [PATCH 2/2] Move general description back to top and use short introduction for usage --- README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6967450c..4e4ee3d0 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,11 @@ Event loop abstraction layer that libraries can use for evented I/O. +In order for async based libraries to be interoperable, they need to use the +same event loop. This component provides a common `LoopInterface` that any +library can target. This allows them to be used in the same loop, with one +single `run()` call that is controlled by the user. + > The master branch contains the code for the upcoming 0.5 release. For the code of the current stable 0.4.x release, checkout the [0.4 branch](https://github.com/reactphp/event-loop/tree/0.4). @@ -53,10 +58,8 @@ $loop->run(); ## Usage -In order for async based libraries to be interoperable, they need to use the -same event loop. This component provides a common `LoopInterface` that any -library can target. This allows them to be used in the same loop, with one -single `run()` call that is controlled by the user. +Typical applications use a single event loop which is created at the beginning +and run at the end of the program. ```php // [1]