|
1 | | -# Revolt <a href="blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" valign="middle"></a> |
| 1 | +# Revolt <a href="blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" valign="middle"></a> |
2 | 2 |
|
3 | 3 | Revolt is a rock-solid event loop for concurrent PHP applications. |
| 4 | +The usual PHP application spends most of its time waiting for I/O. |
| 5 | +While PHP is single threaded, [cooperative multitasking](https://en.wikipedia.org/wiki/Cooperative_multitasking) can be used to allow for concurrency by using the waiting time to do different things. |
4 | 6 |
|
5 | | -## Motivation |
6 | | - |
7 | | -Traditionally, PHP has a synchronous execution flow, doing one thing at a time. |
8 | | -If you query a database, you send the query and wait for the response from the database server in a blocking manner. |
| 7 | +PHP's traditional synchronous execution flow is easy to understand. Doing one thing at a time. |
| 8 | +If you query a database, you send the query and wait for a response from the database server. |
9 | 9 | Once you have the response, you can start doing the next thing. |
10 | 10 |
|
11 | | -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. |
12 | | -Making use of the time we usually spend on waiting for I/O can speed up the total execution time. |
| 11 | +Amp, ReactPHP, and other libraries have offered cooperative multitasking in PHP for a long time. |
| 12 | +However, their event-driven nature was incompatible to many existing interfaces and required a different thinking model. |
| 13 | +PHP 8.1 ships with fibers built-in, which offers cooperative multi-threading. |
| 14 | +Calls can be synchronous without promises or callbacks, while still allowing for non-blocking I/O. |
13 | 15 |
|
14 | | -A single scheduler – also called event loop – is required to allow for [cooperative multitasking](https://en.wikipedia.org/wiki/Cooperative_multitasking), which this package provides. |
| 16 | +Every application making use of cooperative multitasking needs a single scheduler (also called event loop), which this package provides. |
| 17 | +Revolt isn't a full-blown framework for writing concurrent PHP applications, but only provides what's necessary as a common base. |
| 18 | +Different (strongly) opinionated libraries can be built on top of it. |
15 | 19 |
|
16 | 20 | ## Installation |
17 | 21 |
|
18 | | -This package can be installed as a [Composer](https://getcomposer.org/) dependency. |
| 22 | +It may surprise people to learn that the PHP standard library already has everything we need to write event-driven and non-blocking applications. |
| 23 | +This package can be installed as a [Composer](https://getcomposer.org/) dependency on PHP 8 and later. |
| 24 | +PHP 8.1 ships with fibers built-in, but users on PHP 8.0 can install [`ext-fiber`](https://github.com/amphp/ext-fiber) with almost identical behavior. |
19 | 25 |
|
20 | 26 | ```bash |
21 | 27 | composer require revolt/event-loop |
22 | 28 | ``` |
23 | 29 |
|
24 | | -This installs the basic building block for building concurrent applications in PHP. |
25 | | - |
26 | | -## Documentation |
27 | | - |
28 | | -Documentation can be found on [`revolt.run`](https://revolt.run/). |
29 | | - |
30 | | -## Requirements |
31 | | - |
32 | | -This package requires at least PHP 8.0. To take advantage of [Fibers](https://wiki.php.net/rfc/fibers), either [`ext-fiber`](https://github.com/amphp/ext-fiber) or PHP 8.1+ is required. |
33 | | - |
34 | | -##### Optional Extensions |
35 | | - |
36 | | -Extensions are only needed if your application necessitates a high numbers of concurrent socket connections, usually this limit is configured up to 1024 file descriptors. |
37 | | - |
38 | | -- [`ev`](https://pecl.php.net/package/ev) |
39 | | -- [`event`](https://pecl.php.net/package/event) |
40 | | -- [`uv`](https://github.com/amphp/ext-uv) |
41 | | - |
42 | | -## Examples |
| 30 | +<small> |
| 31 | + Applications with many concurrent file descriptors require one of the <a href="https://revolt.run/extensions">extensions</a>. |
| 32 | +</small> |
43 | 33 |
|
44 | | -Examples can be found in the [`./examples`](./examples) directory of this repository. |
| 34 | +→ [View documentation](https://revolt.run/) |
| 35 | +<br> |
| 36 | +→ [View examples](./examples) |
| 37 | +<br> |
45 | 38 |
|
46 | 39 | ## Versioning |
47 | 40 |
|
48 | 41 | `revolt/event-loop` follows the [semver](https://semver.org/) semantic versioning specification. |
49 | 42 |
|
50 | 43 | ## License |
51 | 44 |
|
52 | | -The MIT License (MIT). Please see [`LICENSE`](./LICENSE) for more information. |
| 45 | +The MIT License (MIT). Please see [`LICENSE`](./LICENSE) file for more information. |
53 | 46 |
|
54 | | -Revolt is the result of combining years of experience of amphp's and ReactPHP's |
55 | | -event loop implementations. |
| 47 | +Revolt is the result of combining years of experience of Amp's and ReactPHP's event loop implementations. |
0 commit comments