From d52bb1bc683e9aa5c5e2e3934b03e7049955e777 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Tue, 12 Jul 2022 13:43:14 +0200 Subject: [PATCH] Built-in support for fibers on PHP 8.1 with stable reactphp/async --- composer.json | 4 +- docs/async/fibers.md | 102 ++++++++++++++----------------------------- 2 files changed, 34 insertions(+), 72 deletions(-) diff --git a/composer.json b/composer.json index f02277f..98027b3 100644 --- a/composer.json +++ b/composer.json @@ -13,13 +13,13 @@ "require": { "php": ">=7.1", "nikic/fast-route": "^1.3", + "react/async": "^4 || ^3", "react/http": "^1.6", "react/promise": "^2.7" }, "require-dev": { "phpunit/phpunit": "^9.5 || ^7.5", - "psr/container": "^2 || ^1", - "react/async": "^4@dev || ^3@dev" + "psr/container": "^2 || ^1" }, "autoload": { "psr-4": { diff --git a/docs/async/fibers.md b/docs/async/fibers.md index fc643f9..4a4f126 100644 --- a/docs/async/fibers.md +++ b/docs/async/fibers.md @@ -43,32 +43,44 @@ return value. ## Requirements -At the moment, fibers are available as a development version by installing -[react/async](https://github.com/reactphp/async) from a development branch -like this: +X provides support for fibers out of the box, so there's nothing special you +have to install. You wouldn't usually have to directly interface with fibers, +but the underlying APIs are provided thanks to the common +[reactphp/async](https://github.com/reactphp/async) package. -```bash -$ composer require react/async:^4@dev -``` - -Installing this package version requires PHP 8.1+ (2021-11-25) as fibers are a -core ingredient of PHP 8.1+. We understand that adoption of this very new PHP -version is going to take some time, so we also provide a limited -[compatibility mode](#compatibility-mode) that also works on PHP 7.1+ to ease -upgrading. +Fibers are a core ingredient of PHP 8.1+ (released 2021-11-25), but the same +syntax also works on older PHP versions to some degree if you only have limited +concurrency. For production usage, we highly recommend using PHP 8.1+. -> ℹ️ **Coroutines and Promises work anywhere** +> ⚠️ **Compatibility mode** +> +> For production usage, we highly recommend using PHP 8.1+. If you're using the +> `await()` function in compatibility mode with older PHP versions, it may stop +> the loop from running and may print a warning like this: +> +> ``` +> Warning: Loop restarted. Upgrade to react/async v4 recommended […] +> ``` +> +> Internally, the compatibility mode will cause recursive loop executions when +> dealing with concurrent requests. This should work fine for development +> purposes and fast controllers with low concurrency, but may cause issues in +> production with high concurrency. > -> Remember, we also provide support for [coroutines](coroutines.md) and -> [promises](promises.md) on all supported PHP versions as an alternative. -> Coroutines allow consuming async APIs in a way that resembles a synchronous -> code flow using the `yield` keyword. You can also directly use promises as a -> core building block used in all our async APIs for maximum performance. +> We understand that adoption of this very new PHP version is going to take some +> time and we acknowledge that this is probably one of the largest limitations +> of using fibers at the moment for many. We're committed to providing long-term +> support (LTS) options and providing a smooth upgrade path. As such, we also +> provide limited support for older PHP versions using a compatible API without +> taking advantage of newer language features. This way, you have a much +> smoother upgrade path, as you can already start using the future API for +> testing and development purposes and upgrade your PHP version for production +> use at a later time. ## Usage -Once installed (see requirements above), fibers are very easy to use – because -you simply can't see them – which in turn makes them quite hard to explain. +Fibers are very easy to use – because you simply can't see them – which in turn +makes them a bit harder to explain. The gist is that whenever you're working with an async API that returns a promise, you simply call the `await()` function on it in order to "await" its @@ -124,56 +136,6 @@ Coroutines allow consuming async APIs in a way that resembles a synchronous code flow using the `yield` keyword. You can also directly use promises as a core building block used in all our async APIs for maximum performance. -### Compatibility mode - -Fibers are a core ingredient of PHP 8.1+, but the same syntax also works on -older PHP versions to some degree if you only have limited concurrency. - -For production usage, we highly recommend using PHP 8.1+. At the moment, fibers -are available as a development version by installing -[react/async](https://github.com/reactphp/async) from a development branch -like this: - -```bash -$ composer require react/async:^4@dev -``` - -Installing this package version requires PHP 8.1+ (2021-11-25) as fibers are a -core ingredient of PHP 8.1+. We understand that adoption of this very new PHP -version is going to take some time, so we acknowledge that this is probably one -of the largest limitations of using fibers at the moment. - -But don't worry, we're committed to providing long-term support (LTS) options -and providing a smooth upgrade path. As such, we also provide limited support -for older PHP versions using a compatible API without taking advantage of newer -language features. By installing the v3 development version of this package, the -same `await()` syntax also works on PHP 7.1+ to some degree if you only have -limited concurrency. You can install either supported development version like -this: - -```bash -$ composer require react/async:"^4@dev || ^3@dev" -``` - -This way, you have a much smoother upgrade path, as you can already start using -the future API for testing and development purposes and upgrade your PHP version -for production use at a later time. - -> ⚠️ **Production usage** -> -> For production usage, we highly recommend using PHP 8.1+. If you're using the -> `await()` function in compatibility mode, it may stop the loop from running and -> may print a warning like this: -> -> ``` -> Warning: Loop restarted. Upgrade to react/async v4 recommended […] -> ``` -> -> Internally, the compatibility mode will cause recursive loop executions when -> dealing with concurrent requests. This should work fine for development -> purposes and fast controllers with low concurrency, but may cause issues in -> production with high concurrency. - ### How do fibers work? Fibers are a means of creating code blocks that can be paused and resumed, but