Skip to content

Commit 2090e91

Browse files
jsorjsor
committed
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
1 parent ef22aec commit 2090e91

1 file changed

Lines changed: 100 additions & 31 deletions

File tree

‎README.md‎

Lines changed: 100 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,20 @@
55

66
Event loop abstraction layer that libraries can use for evented I/O.
77

8-
In order for async based libraries to be interoperable, they need to use the
9-
same event loop. This component provides a common `LoopInterface` that any
10-
library can target. This allows them to be used in the same loop, with one
11-
single `run` call that is controlled by the user.
12-
138
> The master branch contains the code for the upcoming 0.5 release.
149
For the code of the current stable 0.4.x release, checkout the
1510
[0.4 branch](https://github.com/reactphp/event-loop/tree/0.4).
1611

17-
In addition to the interface there are some implementations provided:
18-
19-
* `StreamSelectLoop`: This is the only implementation which works out of the
20-
box with PHP. It does a simple `select` system call. It's not the most
21-
performant of loops, but still does the job quite well.
22-
23-
* `LibEventLoop`: This uses the `libevent` pecl extension. `libevent` itself
24-
supports a number of system-specific backends (epoll, kqueue).
25-
26-
* `LibEvLoop`: This uses the `libev` pecl extension
27-
([github](https://github.com/m4rw3r/php-libev)). It supports the same
28-
backends as libevent.
12+
**Table of Contents**
2913

30-
* `ExtEventLoop`: This uses the `event` pecl extension. It supports the same
31-
backends as libevent.
14+
* [Quickstart example](#quickstart-example)
15+
* [Usage](#usage)
16+
* [Loop implementations](#loop-implementations)
17+
* [Install](#install)
18+
* [Tests](#tests)
19+
* [License](#license)
3220

33-
All of the loops support these features:
34-
35-
* File descriptor polling
36-
* One-off timers
37-
* Periodic timers
38-
* Deferred execution of callbacks
39-
40-
## Usage
21+
## Quickstart example
4122

4223
Here is an async HTTP server built with just the event loop.
4324

@@ -46,6 +27,7 @@ $loop = React\EventLoop\Factory::create();
4627

4728
$server = stream_socket_server('tcp://127.0.0.1:8080');
4829
stream_set_blocking($server, 0);
30+
4931
$loop->addReadStream($server, function ($server) use ($loop) {
5032
$conn = stream_socket_accept($server);
5133
$data = "HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nHi\n";
@@ -69,7 +51,94 @@ $loop->addPeriodicTimer(5, function () {
6951
$loop->run();
7052
```
7153

72-
**Note:** The factory is just for convenience. It tries to pick the best
73-
available implementation. Libraries `SHOULD` allow the user to inject an
74-
instance of the loop. They `MAY` use the factory when the user did not supply
75-
a loop.
54+
## Usage
55+
56+
In order for async based libraries to be interoperable, they need to use the
57+
same event loop. This component provides a common `LoopInterface` that any
58+
library can target. This allows them to be used in the same loop, with one
59+
single `run()` call that is controlled by the user.
60+
61+
```php
62+
// [1]
63+
$loop = React\EventLoop\Factory::create();
64+
65+
// [2]
66+
$loop->addPeriodicTimer(1, function () {
67+
echo "Tick\n";
68+
});
69+
70+
$stream = new React\Stream\ReadableResourceStream(
71+
fopen('file.txt', 'r'),
72+
$loop
73+
);
74+
75+
// [3]
76+
$loop->run();
77+
```
78+
79+
1. The loop instance is created at the beginning of the program. A convenience
80+
factory `React\EventLoop\Factory::create()` is provided by this library which
81+
picks the best available [loop implementation](#loop-implementations).
82+
2. The loop instance is used directly or passed to library and application code.
83+
In this example, a periodic timer is registered with the event loop which
84+
simply outputs `Tick` every second and a
85+
[readable stream](https://github.com/reactphp/stream#readableresourcestream)
86+
is created by using ReactPHP's
87+
[stream component](https://github.com/reactphp/stream) for demonstration
88+
purposes.
89+
3. The loop is run with a single `$loop->run()` call at the end of the program.
90+
91+
## Loop implementations
92+
93+
In addition to the interface there are the following implementations provided:
94+
95+
* `StreamSelectLoop`: This is the only implementation which works out of the
96+
box with PHP. It does a simple `select` system call. It's not the most
97+
performant of loops, but still does the job quite well.
98+
99+
* `LibEventLoop`: This uses the `libevent` pecl extension. `libevent` itself
100+
supports a number of system-specific backends (epoll, kqueue).
101+
102+
* `LibEvLoop`: This uses the `libev` pecl extension
103+
([github](https://github.com/m4rw3r/php-libev)). It supports the same
104+
backends as libevent.
105+
106+
* `ExtEventLoop`: This uses the `event` pecl extension. It supports the same
107+
backends as libevent.
108+
109+
All of the loops support these features:
110+
111+
* File descriptor polling
112+
* One-off timers
113+
* Periodic timers
114+
* Deferred execution of callbacks
115+
116+
## Install
117+
118+
The recommended way to install this library is [through Composer](http://getcomposer.org).
119+
[New to Composer?](http://getcomposer.org/doc/00-intro.md)
120+
121+
This will install the latest supported version:
122+
123+
```bash
124+
$ composer require react/event-loop
125+
```
126+
127+
## Tests
128+
129+
To run the test suite, you first need to clone this repo and then install all
130+
dependencies [through Composer](http://getcomposer.org):
131+
132+
```bash
133+
$ composer install
134+
```
135+
136+
To run the test suite, go to the project root and run:
137+
138+
```bash
139+
$ php vendor/bin/phpunit
140+
```
141+
142+
## License
143+
144+
MIT, see [LICENSE file](LICENSE).

0 commit comments

Comments
 (0)