Use cancellation as parameter name for CancellationToken

src/Future.php

@@ -18,7 +18,7 @@ final class Future
      * @template Tv
      *
      * @param iterable<Tk, Future<Tv>> $futures
-     * @param CancellationToken|null $token Optional cancellation token.
+     * @param CancellationToken|null   $token Optional cancellation token.
      *
      * @return iterable<Tk, Future<Tv>>
      */
@@ -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<T>
      */
     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);
         }
     }
 }

src/Future/functions.php

@@ -13,16 +13,16 @@ use Amp\Future;
  *
  * @template T
  *
- * @param iterable<Future<T>> $futures
- * @param CancellationToken|null $token Optional cancellation token.
+ * @param iterable<Future<T>>    $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<Tk, Future<Tv>> $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<Tk, Future<Tv>> $futures
- * @param CancellationToken|null $token Optional cancellation token.
+ * @param CancellationToken|null   $cancellation Optional cancellation token.
  *
  * @return non-empty-array<Tk, Tv>
  *
  * @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<Tk, Future<Tv>> $futures
- * @param CancellationToken|null $token Optional cancellation token.
+ * @param CancellationToken|null   $cancellation Optional cancellation token.
+ *
  * @return array{array<Tk, \Throwable>, array<Tk, Tv>}
  */
-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<Tk, Future<Tv>> $futures
- * @param CancellationToken|null $token Optional cancellation token.
+ * @param CancellationToken|null   $cancellation Optional cancellation token.
  *
  * @return array<Tk, Tv> 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();
     }
 

src/Internal/FutureIterator.php

@@ -25,7 +25,7 @@ final class FutureIterator
     private string $cancellationId;
 
     /**
-     * @var Future<null>|Future<never-return>|null
+     * @var Future<null>|Future<never>|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,