10000 Restructure and improve README · Undefined-Variables/event-loop@03f6d8f · GitHub
[go: up one dir, main page]
Skip to content

Commit 03f6d8f

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 ae8fe72 commit 03f6d8f

File tree

1 file changed

+100
-31
lines changed

1 file changed

+100
-31
lines changed

‎README.md

Lines changed: 100 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -5,35 +5,16 @@
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-
13-
In addition to the interface there are some implementations provided:
14-
15-
* `StreamSelectLoop`: This is the only implementation which works out of the
16-
box with PHP. It does a simple `select` system call. It's not the most
17-
performant of loops, but still does the job quite well.
18-
19-
* `LibEventLoop`: This uses the `libevent` pecl extension. `libevent` itself
20-
supports a number of system-specific backends (epoll, kqueue).
21-
22-
* `LibEvLoop`: This uses the `libev` pecl extension
23-
([github](https://github.com/m4rw3r/php-libev)). It supports the same
24-
backends as libevent.
8+
**Table of Contents**
259

26-
* `ExtEventLoop`: This uses the `event` pecl extension. It supports the same
27-
backends as libevent.
10+
* [Quickstart example](#quickstart-example)
11+
* [Usage](#usage)
12+
* [Loop implementations](#loop-implementations)
13+
* [Install](#install)
14+
* [Tests](#tests)
15+
* [License](#license)
2816

29-
All of the loops support these features:
30-
31-
* File descriptor polling
32-
* One-off timers
33-
* Periodic timers
34-
* Deferred execution of callbacks
35-
36-
## Usage
17+
## Quickstart example
3718

3819
Here is an async HTTP server built with just the event loop.
3920

@@ -42,6 +23,7 @@ $loop = React\EventLoop\Factory::create();
4223

4324
$server = stream_socket_server('tcp://127.0.0.1:8080');
4425
stream_set_blocking($server, 0);
26+
4527
$loop->addReadStream($server, function ($server) use ($loop) {
4628
$conn = stream_socket_accept($server);
4729
$data = "HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\nHi\n";
@@ -65,7 +47,94 @@ $loop->addPeriodicTimer(5, function () {
6547
$loop->run();
6648
```
6749

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

0 commit comments

Comments
 (0)
0