danog/amp
1
0
Fork 0
mirror of https://github.com/danog/amp.git synced 2024-12-02 09:27:46 +01:00
Code Issues Projects Releases Wiki Activity

Rename combinators, introduce CompositeLengthException (#383)

Browse Source
This commit is contained in:
Niklas Keller 2022-01-16 17:39:04 +01:00 committed by GitHub
parent cadf1c0069
commit 2a076099dd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 202 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/CompositeException.php
View File

@ -11,7 +11,7 @@ final class CompositeException extends \Exception
/**
* @param non-empty-array<array-key, \Throwable> $reasons Array of exceptions.
* @param string|null $message Exception message, defaults to message generated from passed exceptions.
* @param string|null $message Exception message, defaults to message generated from passed exceptions.
*
* @psalm-assert non-empty-array<array-key, \Throwable> $reasons
*/
@ -36,7 +36,7 @@ final class CompositeException extends \Exception
private function generateMessage(array $reasons): string
{
$message = \sprintf(
'Multiple errors encountered (%d); use "%s::getReasons()" to retrieve the array of exceptions thrown:',
'Multiple exceptions encountered (%d); use "%s::getReasons()" to retrieve the array of exceptions thrown:',
\count($reasons),
self::class
);

11
src/CompositeLengthException.php Normal file
View File

@ -0,0 +1,11 @@
<?php
namespace Amp;
final class CompositeLengthException extends \Exception
{
public function __construct(string $message)
{
parent::__construct($message);
}
}

156
src/Future/functions.php
View File

@ -4,6 +4,7 @@ namespace Amp\Future;
use Amp\Cancellation;
use Amp\CompositeException;
use Amp\CompositeLengthException;
use Amp\Future;
/**
@ -14,57 +15,106 @@ use Amp\Future;
* @template T
*
* @param iterable<Future<T>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return T
*
* @throws \Error If $futures is empty.
* @throws CompositeLengthException If {@code $futures} is empty.
*/
function race(iterable $futures, ?Cancellation $cancellation = null): mixed
function awaitFirst(iterable $futures, ?Cancellation $cancellation = null): mixed
{
foreach (Future::iterate($futures, $cancellation) as $first) {
return $first->await();
}
throw new \Error('No future provided');
throw new CompositeLengthException('Argument #1 ($futures) is empty');
}
/**
* Unwraps the first successfully completed future.
* Unwraps the first completed future.
*
* If you want the first future completed, successful or not, use {@see race()} instead.
* If you want the first future completed without an error, use {@see any()} instead.
*
* @template T
*
* @param iterable<Future<T>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return T
*
* @throws CompositeLengthException If $futures is empty.
*
* @deprecated Use {@see awaitFirst()} instead.
*/
function race(iterable $futures, ?Cancellation $cancellation = null): mixed
{
return awaitFirst($futures, $cancellation);
}
/**
* Awaits the first successfully completed future, ignoring errors.
*
* If you want the first future completed, successful or not, use {@see awaitFirst()} instead.
*
* @template Tk of array-key
* @template Tv
*
* @param iterable<Tk, Future<Tv>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return Tv
*
* @throws CompositeException If all futures errored.
* @throws CompositeLengthException If {@code $futures} is empty.
*/
function any(iterable $futures, ?Cancellation $cancellation = null): mixed
function awaitAny(iterable $futures, ?Cancellation $cancellation = null): mixed
{
$result = some($futures, 1, $cancellation);
$result = awaitAnyN(1, $futures, $cancellation);
return $result[\array_key_first($result)];
}
/**
* Awaits the first successfully completed future, ignoring errors.
*
* If you want the first future completed, successful or not, use {@see awaitFirst()} instead.
*
* @template Tk of array-key
* @template Tv
*
* @param iterable<Tk, Future<Tv>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return Tv
*
* @throws CompositeException If all futures errored.
* @throws CompositeLengthException If {@code $futures} is empty.
*
* @deprecated Use {@see awaitFirst()} instead.
*/
function any(iterable $futures, ?Cancellation $cancellation = null): mixed
{
return awaitAny($futures, $cancellation);
}
/**
* Awaits the first N successfully completed futures, ignoring errors.
*
* @template Tk of array-key
* @template Tv
*
* @param positive-int $count
* @param iterable<Tk, Future<Tv>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return non-empty-array<Tk, Tv>
*
* @throws CompositeException If all futures errored.
* @throws CompositeException If too many futures errored.
* @throws CompositeLengthException If {@code $futures} is empty.
*/
function some(iterable $futures, int $count, ?Cancellation $cancellation = null): array
function awaitAnyN(int $count, iterable $futures, ?Cancellation $cancellation = null): array
{
if ($count <= 0) {
throw new \ValueError('The count must be greater than 0, got ' . $count);
throw new \ValueError('Argument #1 ($count) must be greater than 0, got ' . $count);
}
$values = [];
@ -81,8 +131,8 @@ function some(iterable $futures, int $count, ?Cancellation $cancellation = null)
}
}
if (empty($errors)) {
throw new \Error('Iterable did provide enough futures to satisfy the required count of ' . $count);
if (\count($values) + \count($errors) < $count) {
throw new CompositeLengthException('Argument #2 ($futures) contains too few futures to satisfy the required count of ' . $count);
}
/**
@ -96,11 +146,35 @@ function some(iterable $futures, int $count, ?Cancellation $cancellation = null)
* @template Tv
*
* @param iterable<Tk, Future<Tv>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
* @param positive-int $count
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return non-empty-array<Tk, Tv>
*
* @throws CompositeException If all futures errored.
* @throws CompositeLengthException If {@code $futures} is empty.
*
* @deprecated Use {@see awaitAnyN()} instead.
*/
function some(iterable $futures, int $count, ?Cancellation $cancellation = null): array
{
return awaitAnyN($count, $futures, $cancellation);
}
/**
* Awaits all futures to complete or error.
*
* This awaits all futures without aborting on first error (unlike {@see await()}).
*
* @template Tk of array-key
* @template Tv
*
* @param iterable<Tk, Future<Tv>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return array{array<Tk, \Throwable>, array<Tk, Tv>}
*/
function settle(iterable $futures, ?Cancellation $cancellation = null): array
function awaitAll(iterable $futures, ?Cancellation $cancellation = null): array
{
$values = [];
$errors = [];
@ -117,18 +191,39 @@ function settle(iterable $futures, ?Cancellation $cancellation = null): array
}
/**
* Awaits all futures to complete or aborts if any errors. The returned array keys will be in the order the futures
* resolved, not in the order given by the iterable. Sort the array after resolution if necessary.
* @template Tk of array-key
* @template Tv
*
* @param iterable<Tk, Future<Tv>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return array{array<Tk, \Throwable>, array<Tk, Tv>}
*
* @deprecated Use {@see awaitAll()} instead.
*/
function settle(iterable $futures, ?Cancellation $cancellation = null): array
{
return awaitAll($futures, $cancellation);
}
/**
* Awaits all futures to complete or aborts if any errors.
*
* The returned array keys will be in the order the futures resolved, not in the order given by the iterable.
* Sort the array after completion if necessary.
*
* This is equivalent to awaiting all futures in a loop, except that it aborts as soon as one of the futures errors
* instead of relying on the order in the iterable and awaiting the futures sequentially.
*
* @template Tk of array-key
* @template Tv
*
* @param iterable<Tk, Future<Tv>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return array<Tk, Tv> Unwrapped values with the order preserved.
*/
function all(iterable $futures, Cancellation $cancellation = null): array
function await(iterable $futures, ?Cancellation $cancellation = null): array
{
$values = [];
@ -140,3 +235,22 @@ function all(iterable $futures, Cancellation $cancellation = null): array
/** @var array<Tk, Tv> */
return $values;
}
/**
* Awaits all futures to complete or aborts if any errors. The returned array keys will be in the order the futures
* resolved, not in the order given by the iterable. Sort the array after resolution if necessary.
*
* @template Tk of array-key
* @template Tv
*
* @param iterable<Tk, Future<Tv>> $futures
* @param Cancellation|null $cancellation Optional cancellation.
*
* @return array<Tk, Tv> Unwrapped values with the order preserved.
*
* @deprecated Use {@see await()} instead.
*/
function all(iterable $futures, ?Cancellation $cancellation = null): array
{
return await($futures, $cancellation);
}

16
test/Future/SettleTest.php → test/Future/AwaitAllTest.php
View File

@ -9,16 +9,16 @@ use Amp\TimeoutCancellation;
use PHPUnit\Framework\TestCase;
use Revolt\EventLoop;
class SettleTest extends TestCase
class AwaitAllTest extends TestCase
{
public function testSingleComplete(): void
{
self::assertSame([[], [42]], settle([Future::complete(42)]));
self::assertSame([[], [42]], awaitAll([Future::complete(42)]));
}
public function testTwoComplete(): void
{
self::assertSame([[], [1, 2]], settle([Future::complete(1), Future::complete(2)]));
self::assertSame([[], [1, 2]], awaitAll([Future::complete(1), Future::complete(2)]));
}
public function testTwoFirstThrowing(): void
@ -26,7 +26,7 @@ class SettleTest extends TestCase
$exception = new \Exception('foo');
self::assertSame(
[['one' => $exception], ['two' => 2]],
settle(['one' => Future::error($exception), 'two' => Future::complete(2)])
awaitAll(['one' => Future::error($exception), 'two' => Future::complete(2)])
);
}
@ -34,13 +34,13 @@ class SettleTest extends TestCase
{
$one = new \Exception('foo');
$two = new \RuntimeException('bar');
self::assertSame([[$one, $two], []], Future\settle([Future::error($one), Future::error($two)]));
self::assertSame([[$one, $two], []], Future\awaitAll([Future::error($one), Future::error($two)]));
}
public function testTwoGeneratorThrows(): void
{
$exception = new \Exception('foo');
self::assertSame([[0 => $exception], [1 => 2]], settle((static function () use ($exception) {
self::assertSame([[0 => $exception], [1 => 2]], awaitAll((static function () use ($exception) {
yield Future::error($exception);
yield Future::complete(2);
})()));
@ -55,7 +55,7 @@ class SettleTest extends TestCase
return $deferred;
}, \range(1, 3));
settle(\array_map(
awaitAll(\array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), new TimeoutCancellation(0.05));
@ -69,7 +69,7 @@ class SettleTest extends TestCase
return $deferred;
}, \range(1, 3));
self::assertSame([[], \range(1, 3)], settle(\array_map(
self::assertSame([[], \range(1, 3)], awaitAll(\array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), new TimeoutCancellation(0.5)));

35
test/Future/SomeTest.php → test/Future/AwaitAnyNTest.php
View File

@ -4,53 +4,54 @@ namespace Amp\Future;
use Amp\CancelledException;
use Amp\CompositeException;
use Amp\CompositeLengthException;
use Amp\DeferredFuture;
use Amp\Future;
use Amp\TimeoutCancellation;
use PHPUnit\Framework\TestCase;
use Revolt\EventLoop;
class SomeTest extends TestCase
class AwaitAnyNTest extends TestCase
{
public function testSingleComplete(): void
{
self::assertSame([0 => 42], some([Future::complete(42)], 1));
self::assertSame([0 => 42], awaitAnyN(1, [Future::complete(42)]));
}
public function testTwoComplete(): void
{
self::assertSame([1, 2], some([Future::complete(1), Future::complete(2)], 2));
self::assertSame([1, 2], awaitAnyN(2, [Future::complete(1), Future::complete(2)]));
}
public function testTwoFirstPending(): void
{
$deferred = new DeferredFuture();
self::assertSame([1 => 2], some([$deferred->getFuture(), Future::complete(2)], 1));
self::assertSame([1 => 2], awaitAnyN(1, [$deferred->getFuture(), Future::complete(2)]));
}
public function testTwoFirstThrowing(): void
{
self::assertSame(
['two' => 2],
some(['one' => Future::error(new \Exception('foo')), 'two' => Future::complete(2)], 1)
awaitAnyN(1, ['one' => Future::error(new \Exception('foo')), 'two' => Future::complete(2)])
);
}
public function testTwoBothThrowing(): void
{
$this->expectException(CompositeException::class);
$this->expectExceptionMessage('Multiple errors encountered (2); use "Amp\CompositeException::getReasons()" to retrieve the array of exceptions thrown:');
$this->expectExceptionMessage('Multiple exceptions encountered (2); use "Amp\CompositeException::getReasons()" to retrieve the array of exceptions thrown:');
Future\some([Future::error(new \Exception('foo')), Future::error(new \RuntimeException('bar'))], 2);
Future\awaitAnyN(2, [Future::error(new \Exception('foo')), Future::error(new \RuntimeException('bar'))]);
}
public function testTwoGeneratorThrows(): void
{
self::assertSame([1 => 2], some((static function () {
self::assertSame([1 => 2], awaitAnyN(1, (static function () {
yield Future::error(new \Exception('foo'));
yield Future::complete(2);
})(), 1));
})()));
}
public function testCancellation(): void
@ -62,10 +63,10 @@ class SomeTest extends TestCase
return $deferred;
}, \range(1, 3));
some(\array_map(
awaitAnyN(3, \array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), 3, new TimeoutCancellation(0.05));
), new TimeoutCancellation(0.05));
}
public function testCompleteBeforeCancellation(): void
@ -76,23 +77,23 @@ class SomeTest extends TestCase
return $deferred;
}, \range(1, 3));
self::assertSame(\range(1, 3), some(\array_map(
self::assertSame(\range(1, 3), awaitAnyN(3, \array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), 3, new TimeoutCancellation(0.5)));
), new TimeoutCancellation(0.5)));
}
public function testZero(): void
{
$this->expectException(\ValueError::class);
$this->expectExceptionMessage('greater than 0');
some([], 0);
awaitAnyN(0, []);
}
public function testTooFew(): void
{
$this->expectException(\Error::class);
$this->expectExceptionMessage('required count');
some([Future::complete(1), Future::complete(2)], 3);
$this->expectException(CompositeLengthException::class);
$this->expectExceptionMessage('Argument #2 ($futures) contains too few futures to satisfy the required count of 3');
awaitAnyN(3, [Future::complete(1), Future::complete(2)]);
}
}

20
test/Future/AnyTest.php → test/Future/AwaitAnyTest.php
View File

@ -10,41 +10,41 @@ use Amp\TimeoutCancellation;
use PHPUnit\Framework\TestCase;
use Revolt\EventLoop;
class AnyTest extends TestCase
class AwaitAnyTest extends TestCase
{
public function testSingleComplete(): void
{
self::assertSame(42, any([Future::complete(42)]));
self::assertSame(42, awaitAny([Future::complete(42)]));
}
public function testTwoComplete(): void
{
self::assertSame(1, any([Future::complete(1), Future::complete(2)]));
self::assertSame(1, awaitAny([Future::complete(1), Future::complete(2)]));
}
public function testTwoFirstPending(): void
{
$deferred = new DeferredFuture();
self::assertSame(2, any([$deferred->getFuture(), Future::complete(2)]));
self::assertSame(2, awaitAny([$deferred->getFuture(), Future::complete(2)]));
}
public function testTwoFirstThrowing(): void
{
self::assertSame(2, any([Future::error(new \Exception('foo')), Future::complete(2)]));
self::assertSame(2, awaitAny([Future::error(new \Exception('foo')), Future::complete(2)]));
}
public function testTwoBothThrowing(): void
{
$this->expectException(CompositeException::class);
$this->expectExceptionMessage('Multiple errors encountered (2); use "Amp\CompositeException::getReasons()" to retrieve the array of exceptions thrown:');
$this->expectExceptionMessage('Multiple exceptions encountered (2); use "Amp\CompositeException::getReasons()" to retrieve the array of exceptions thrown:');
Future\any([Future::error(new \Exception('foo')), Future::error(new \RuntimeException('bar'))]);
Future\awaitAny([Future::error(new \Exception('foo')), Future::error(new \RuntimeException('bar'))]);
}
public function testTwoGeneratorThrows(): void
{
self::assertSame(2, any((static function () {
self::assertSame(2, awaitAny((static function () {
yield Future::error(new \Exception('foo'));
yield Future::complete(2);
})()));
@ -59,7 +59,7 @@ class AnyTest extends TestCase
return $deferred;
}, \range(1, 3));
any(\array_map(
awaitAny(\array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), new TimeoutCancellation(0.05));
@ -78,7 +78,7 @@ class AnyTest extends TestCase
\array_unshift($deferreds, $deferred);
self::assertSame(1, any(\array_map(
self::assertSame(1, awaitAny(\array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), new TimeoutCancellation(0.2)));

16
test/Future/RaceTest.php → test/Future/AwaitFirstTest.php
View File

@ -9,23 +9,23 @@ use Amp\TimeoutCancellation;
use PHPUnit\Framework\TestCase;
use Revolt\EventLoop;
class RaceTest extends TestCase
class AwaitFirstTest extends TestCase
{
public function testSingleComplete(): void
{
self::assertSame(42, race([Future::complete(42)]));
self::assertSame(42, awaitFirst([Future::complete(42)]));
}
public function testTwoComplete(): void
{
self::assertSame(1, Future\race([Future::complete(1), Future::complete(2)]));
self::assertSame(1, Future\awaitFirst([Future::complete(1), Future::complete(2)]));
}
public function testTwoFirstPending(): void
{
$deferred = new DeferredFuture;
self::assertSame(2, Future\race([$deferred->getFuture(), Future::complete(2)]));
self::assertSame(2, Future\awaitFirst([$deferred->getFuture(), Future::complete(2)]));
}
public function testTwoFirstThrowing(): void
@ -33,7 +33,7 @@ class RaceTest extends TestCase
$this->expectException(\Exception::class);
$this->expectExceptionMessage('foo');
race([Future::error(new \Exception('foo')), Future::complete(2)]);
awaitFirst([Future::error(new \Exception('foo')), Future::complete(2)]);
}
public function testTwoGeneratorThrows(): void
@ -41,7 +41,7 @@ class RaceTest extends TestCase
$this->expectException(\Exception::class);
$this->expectExceptionMessage('foo');
race((static function () {
awaitFirst((static function () {
yield Future::error(new \Exception('foo'));
yield Future::complete(2);
})());
@ -57,7 +57,7 @@ class RaceTest extends TestCase
return $deferred;
}, \range(1, 3));
race(\array_map(
awaitFirst(\array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), new TimeoutCancellation(0.05));
@ -71,7 +71,7 @@ class RaceTest extends TestCase
return $deferred;
}, \range(1, 3));
self::assertSame(1, race(\array_map(
self::assertSame(1, awaitFirst(\array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), new TimeoutCancellation(0.2)));

20
test/Future/AllTest.php → test/Future/AwaitTest.php
View File

@ -9,16 +9,16 @@ use Amp\TimeoutCancellation;
use PHPUnit\Framework\TestCase;
use Revolt\EventLoop;
class AllTest extends TestCase
class AwaitTest extends TestCase
{
public function testSingleComplete(): void
{
self::assertSame([42], all([Future::complete(42)]));
self::assertSame([42], await([Future::complete(42)]));
}
public function testTwoComplete(): void
{
self::assertSame([1, 2], all([Future::complete(1), Future::complete(2)]));
self::assertSame([1, 2], await([Future::complete(1), Future::complete(2)]));
}
public function testTwoFirstPending(): void
@ -27,7 +27,7 @@ class AllTest extends TestCase
EventLoop::delay(0.01, fn () => $deferred->complete(1));
self::assertSame([1 => 2, 0 => 1], all([$deferred->getFuture(), Future::complete(2)]));
self::assertSame([1 => 2, 0 => 1], await([$deferred->getFuture(), Future::complete(2)]));
}
public function testArrayDestructuring(): void
@ -36,7 +36,7 @@ class AllTest extends TestCase
EventLoop::delay(0.01, fn () => $deferred->complete(1));
[$first, $second] = all([$deferred->getFuture(), Future::complete(2)]);
[$first, $second] = await([$deferred->getFuture(), Future::complete(2)]);
self::assertSame(1, $first);
self::assertSame(2, $second);
@ -47,7 +47,7 @@ class AllTest extends TestCase
$this->expectException(\Exception::class);
$this->expectExceptionMessage('foo');
all([Future::error(new \Exception('foo')), Future::complete(2)]);
await([Future::error(new \Exception('foo')), Future::complete(2)]);
}
public function testTwoThrowingWithOneLater(): void
@ -58,7 +58,7 @@ class AllTest extends TestCase
$deferred = new DeferredFuture;
EventLoop::delay(0.1, static fn () => $deferred->error(new \Exception('bar')));
all([Future::error(new \Exception('foo')), $deferred->getFuture()]);
await([Future::error(new \Exception('foo')), $deferred->getFuture()]);
}
public function testTwoGeneratorThrows(): void
@ -66,7 +66,7 @@ class AllTest extends TestCase
$this->expectException(\Exception::class);
$this->expectExceptionMessage('foo');
all((static function () {
await((static function () {
yield Future::error(new \Exception('foo'));
yield Future::complete(2);
})());
@ -81,7 +81,7 @@ class AllTest extends TestCase
return $deferred;
}, \range(1, 3));
all(\array_map(
await(\array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), new TimeoutCancellation(0.2));
@ -95,7 +95,7 @@ class AllTest extends TestCase
return $deferred;
}, \range(1, 3));
self::assertSame([1, 2, 3], all(\array_map(
self::assertSame([1, 2, 3], await(\array_map(
fn (DeferredFuture $deferred) => $deferred->getFuture(),
$deferreds
), new TimeoutCancellation(0.5)));