From d9f50cfd624f3a5cf871f9cdfeda56e929341249 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Wed, 20 Oct 2021 15:45:05 +0200 Subject: [PATCH] Add documentation to describe limitations of blocking vs async APIs --- README.md | 28 ++++++++++++++++++++++++++++ src/functions.php | 28 ++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/README.md b/README.md index edf87a9..6ea17a9 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,13 @@ use the [default loop](https://github.com/reactphp/event-loop#loop). This value SHOULD NOT be given unless you're sure you want to explicitly use a given event loop instance. +Note that this function will assume control over the event loop. Internally, it +will actually `run()` the loop until the timer fires and then calls `stop()` to +terminate execution of the loop. This means this function is more suited for +short-lived program executions when using async APIs is not feasible. For +long-running applications, using event-driven APIs by leveraging timers +is usually preferable. + ### await() The `await(PromiseInterface $promise, ?LoopInterface $loop = null, ?float $timeout = null): mixed` function can be used to @@ -170,6 +177,13 @@ timeout triggers, this will `cancel()` the promise and throw a `TimeoutException This implies that if you pass a really small (or negative) value, it will still start a timer and will thus trigger at the earliest possible time in the future. +Note that this function will assume control over the event loop. Internally, it +will actually `run()` the loop until the promise settles and then calls `stop()` to +terminate execution of the loop. This means this function is more suited for +short-lived promise executions when using promise-based APIs is not feasible. +For long-running applications, using promise-based APIs by leveraging chained +`then()` calls is usually preferable. + ### awaitAny() The `awaitAny(PromiseInterface[] $promises, ?LoopInterface $loop = null, ?float $timeout = null): mixed` function can be used to @@ -216,6 +230,13 @@ the timeout triggers, this will `cancel()` all pending promises and throw a value, it will still start a timer and will thus trigger at the earliest possible time in the future. +Note that this function will assume control over the event loop. Internally, it +will actually `run()` the loop until the promise settles and then calls `stop()` to +terminate execution of the loop. This means this function is more suited for +short-lived promise executions when using promise-based APIs is not feasible. +For long-running applications, using promise-based APIs by leveraging chained +`then()` calls is usually preferable. + ### awaitAll() The `awaitAll(PromiseInterface[] $promises, ?LoopInterface $loop = null, ?float $timeout = null): mixed[]` function can be used to @@ -265,6 +286,13 @@ the timeout triggers, this will `cancel()` all pending promises and throw a value, it will still start a timer and will thus trigger at the earliest possible time in the future. +Note that this function will assume control over the event loop. Internally, it +will actually `run()` the loop until the promise settles and then calls `stop()` to +terminate execution of the loop. This means this function is more suited for +short-lived promise executions when using promise-based APIs is not feasible. +For long-running applications, using promise-based APIs by leveraging chained +`then()` calls is usually preferable. + ## Install The recommended way to install this library is [through Composer](https://getcomposer.org). diff --git a/src/functions.php b/src/functions.php index cf23fc0..6afe2e0 100644 --- a/src/functions.php +++ b/src/functions.php @@ -35,6 +35,13 @@ * SHOULD NOT be given unless you're sure you want to explicitly use a given event * loop instance. * + * Note that this function will assume control over the event loop. Internally, it + * will actually `run()` the loop until the timer fires and then calls `stop()` to + * terminate execution of the loop. This means this function is more suited for + * short-lived program executions when using async APIs is not feasible. For + * long-running applications, using event-driven APIs by leveraging timers + * is usually preferable. + * * @param float $time * @param ?LoopInterface $loop * @return void @@ -92,6 +99,13 @@ function sleep($time, LoopInterface $loop = null) * This implies that if you pass a really small (or negative) value, it will still * start a timer and will thus trigger at the earliest possible time in the future. * + * Note that this function will assume control over the event loop. Internally, it + * will actually `run()` the loop until the promise settles and then calls `stop()` to + * terminate execution of the loop. This means this function is more suited for + * short-lived promise executions when using promise-based APIs is not feasible. + * For long-running applications, using promise-based APIs by leveraging chained + * `then()` calls is usually preferable. + * * @param PromiseInterface $promise * @param ?LoopInterface $loop * @param ?float $timeout [deprecated] (optional) maximum timeout in seconds or null=wait forever @@ -196,6 +210,13 @@ function ($error) use (&$exception, &$rejected, &$wait, $loop) { * value, it will still start a timer and will thus trigger at the earliest * possible time in the future. * + * Note that this function will assume control over the event loop. Internally, it + * will actually `run()` the loop until the promise settles and then calls `stop()` to + * terminate execution of the loop. This means this function is more suited for + * short-lived promise executions when using promise-based APIs is not feasible. + * For long-running applications, using promise-based APIs by leveraging chained + * `then()` calls is usually preferable. + * * @param PromiseInterface[] $promises * @param ?LoopInterface $loop * @param ?float $timeout [deprecated] (optional) maximum timeout in seconds or null=wait forever @@ -287,6 +308,13 @@ function awaitAny(array $promises, LoopInterface $loop = null, $timeout = null) * value, it will still start a timer and will thus trigger at the earliest * possible time in the future. * + * Note that this function will assume control over the event loop. Internally, it + * will actually `run()` the loop until the promise settles and then calls `stop()` to + * terminate execution of the loop. This means this function is more suited for + * short-lived promise executions when using promise-based APIs is not feasible. + * For long-running applications, using promise-based APIs by leveraging chained + * `then()` calls is usually preferable. + * * @param PromiseInterface[] $promises * @param ?LoopInterface $loop * @param ?float $timeout [deprecated] (optional) maximum timeout in seconds or null=wait forever