From e12c20cbda27b3c9086f58718e6d04886b10f18d Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Thu, 2 Dec 2021 21:43:21 +0100 Subject: [PATCH] Use cancellation as parameter name for CancellationToken --- src/Future.php | 12 +++++----- src/Future/functions.php | 40 ++++++++++++++++++--------------- src/Internal/FutureIterator.php | 8 +++---- 3 files changed, 33 insertions(+), 27 deletions(-) diff --git a/src/Future.php b/src/Future.php index b07772a..a1264c8 100644 --- a/src/Future.php +++ b/src/Future.php @@ -18,7 +18,7 @@ final class Future * @template Tv * * @param iterable> $futures - * @param CancellationToken|null $token Optional cancellation token. + * @param CancellationToken|null $token Optional cancellation token. * * @return iterable> */ @@ -121,6 +121,7 @@ final class Future * @template Tr * * @param callable(T):Tr $onComplete + * * @return Future */ public function map(callable $onComplete): self @@ -150,6 +151,7 @@ final class Future * @template Tr * * @param callable(\Throwable):Tr $onError + * * @return Future */ public function catch(callable $onError): self @@ -178,6 +180,7 @@ final class Future * will error with the thrown exception. * * @param callable():void $onSettle + * * @return Future */ public function finally(callable $onSettle): self @@ -208,12 +211,11 @@ final class Future * * @return T */ - public function await(?CancellationToken $token = null): mixed + public function await(?CancellationToken $cancellation = null): mixed { $suspension = EventLoop::createSuspension(); $callbackId = $this->state->subscribe(static function (?\Throwable $error, mixed $value) use ( - $token, $suspension ): void { if ($error) { @@ -224,7 +226,7 @@ final class Future }); $state = $this->state; - $cancellationId = $token?->subscribe(static function (\Throwable $reason) use ( + $cancellationId = $cancellation?->subscribe(static function (\Throwable $reason) use ( $callbackId, $suspension, $state @@ -239,7 +241,7 @@ final class Future return $suspension->suspend(); } finally { /** @psalm-suppress PossiblyNullArgument $cancellationId will not be null if $token is not null. */ - $token?->unsubscribe($cancellationId); + $cancellation?->unsubscribe($cancellationId); } } } diff --git a/src/Future/functions.php b/src/Future/functions.php index 5507efe..bcdc26a 100644 --- a/src/Future/functions.php +++ b/src/Future/functions.php @@ -13,16 +13,16 @@ use Amp\Future; * * @template T * - * @param iterable> $futures - * @param CancellationToken|null $token Optional cancellation token. + * @param iterable> $futures + * @param CancellationToken|null $cancellation Optional cancellation token. * * @return T * * @throws \Error If $futures is empty. */ -function race(iterable $futures, ?CancellationToken $token = null): mixed +function race(iterable $futures, ?CancellationToken $cancellation = null): mixed { - foreach (Future::iterate($futures, $token) as $first) { + foreach (Future::iterate($futures, $cancellation) as $first) { return $first->await(); } @@ -38,15 +38,15 @@ function race(iterable $futures, ?CancellationToken $token = null): mixed * @template Tv * * @param iterable> $futures - * @param CancellationToken|null $token Optional cancellation token. + * @param CancellationToken|null $cancellation Optional cancellation token. * * @return Tv * * @throws CompositeException If all futures errored. */ -function any(iterable $futures, ?CancellationToken $token = null): mixed +function any(iterable $futures, ?CancellationToken $cancellation = null): mixed { - $result = some($futures, 1, $token); + $result = some($futures, 1, $cancellation); return $result[\array_key_first($result)]; } @@ -55,21 +55,22 @@ function any(iterable $futures, ?CancellationToken $token = null): mixed * @template Tv * * @param iterable> $futures - * @param CancellationToken|null $token Optional cancellation token. + * @param CancellationToken|null $cancellation Optional cancellation token. * * @return non-empty-array * * @throws CompositeException If all futures errored. */ -function some(iterable $futures, int $count, ?CancellationToken $token = null): array +function some(iterable $futures, int $count, ?CancellationToken $cancellation = null): array { if ($count <= 0) { - throw new \ValueError('The count must be greater than 0'); + throw new \ValueError('The count must be greater than 0, got ' . $count); } $values = []; $errors = []; - foreach (Future::iterate($futures, $token) as $index => $future) { + + foreach (Future::iterate($futures, $cancellation) as $index => $future) { try { $values[$index] = $future->await(); if (\count($values) === $count) { @@ -81,7 +82,7 @@ function some(iterable $futures, int $count, ?CancellationToken $token = null): } if (empty($errors)) { - throw new \Error('Iterable did provide enough futures to satisfy the required count'); + throw new \Error('Iterable did provide enough futures to satisfy the required count of ' . $count); } /** @@ -95,14 +96,16 @@ function some(iterable $futures, int $count, ?CancellationToken $token = null): * @template Tv * * @param iterable> $futures - * @param CancellationToken|null $token Optional cancellation token. + * @param CancellationToken|null $cancellation Optional cancellation token. + * * @return array{array, array} */ -function settle(iterable $futures, ?CancellationToken $token = null): array +function settle(iterable $futures, ?CancellationToken $cancellation = null): array { $values = []; $errors = []; - foreach (Future::iterate($futures, $token) as $index => $future) { + + foreach (Future::iterate($futures, $cancellation) as $index => $future) { try { $values[$index] = $future->await(); } catch (\Throwable $throwable) { @@ -121,15 +124,16 @@ function settle(iterable $futures, ?CancellationToken $token = null): array * @template Tv * * @param iterable> $futures - * @param CancellationToken|null $token Optional cancellation token. + * @param CancellationToken|null $cancellation Optional cancellation token. * * @return array Unwrapped values with the order preserved. */ -function all(iterable $futures, CancellationToken $token = null): array +function all(iterable $futures, CancellationToken $cancellation = null): array { $values = []; + // Future::iterate() to throw the first error based on completion order instead of argument order - foreach (Future::iterate($futures, $token) as $index => $future) { + foreach (Future::iterate($futures, $cancellation) as $index => $future) { $values[$index] = $future->await(); } diff --git a/src/Internal/FutureIterator.php b/src/Internal/FutureIterator.php index 4391681..d0c84be 100644 --- a/src/Internal/FutureIterator.php +++ b/src/Internal/FutureIterator.php @@ -25,7 +25,7 @@ final class FutureIterator private string $cancellationId; /** - * @var Future|Future|null + * @var Future|Future|null */ private ?Future $complete = null; @@ -55,9 +55,9 @@ final class FutureIterator $queue = $this->queue; // Using separate object to avoid a circular reference. $id = $state->subscribe( - /** - * @param Tv|null $result - */ + /** + * @param Tv|null $result + */ static function (?\Throwable $error, mixed $result, string $id) use ( $key, $future,