diff --git a/src/Awaitable/Awaitable.php b/src/Awaitable/Awaitable.php index 0227a69..07064bf 100644 --- a/src/Awaitable/Awaitable.php +++ b/src/Awaitable/Awaitable.php @@ -12,7 +12,7 @@ interface Awaitable { /** - * Assigns a set of callback functions to the promise, and returns a new promise. + * Assigns a set of callback functions to the awaitable, and returns a new awaitable. * * @param callable<(mixed $value): mixed>|null $onFulfilled * @param callable<(Exception $exception): mixed>|null $onRejected @@ -22,7 +22,7 @@ interface Awaitable public function then(callable $onFulfilled = null, callable $onRejected = null); /** - * Assigns a set of callback functions to the promise. Returned values are ignored and thrown exceptions + * Assigns a set of callback functions to the awaitable. Returned values are ignored and thrown exceptions * are rethrown in an uncatchable way. * * @param callable<(mixed $value)>|null $onFulfilled @@ -31,8 +31,8 @@ public function then(callable $onFulfilled = null, callable $onRejected = null); public function done(callable $onFulfilled = null, callable $onRejected = null); /** - * Cancels the promise, signaling that the value is no longer needed. This method should call any appropriate - * cancellation handler, then reject the promise with the given exception or a CancelledException if none is + * Cancels the awaitable, signaling that the value is no longer needed. This method should call any appropriate + * cancellation handler, then reject the awaitable with the given exception or a CancelledException if none is * given. * * @param mixed $reason @@ -40,8 +40,8 @@ public function done(callable $onFulfilled = null, callable $onRejected = null); public function cancel($reason = null); /** - * Cancels the promise with $reason if it is not resolved within $timeout seconds. When the promise resolves, the - * returned promise is fulfilled or rejected with the same value. + * Cancels the awaitable with $reason if it is not resolved within $timeout seconds. When the awaitable resolves, + * the returned awaitable is fulfilled or rejected with the same value. * * @param float $timeout * @param mixed $reason @@ -51,8 +51,8 @@ public function cancel($reason = null); public function timeout($timeout, $reason = null); /** - * Returns a promise that is fulfilled $time seconds after this promise is fulfilled. If the promise is rejected, - * the returned promise is immediately rejected. + * Returns an awaitable that is fulfilled $time seconds after this awaitable is fulfilled. If the promise is + * rejected, the returned awaitable is immediately rejected. * * @param float $time * @@ -61,9 +61,9 @@ public function timeout($timeout, $reason = null); public function delay($time); /** - * Assigns a callback function that is called when the promise is rejected. If a typehint is defined on the callable - * (ex: function (RuntimeException $exception) {}), then the function will only be called if the exception is an - * instance of the typehinted exception. + * Assigns a callback function that is called when the awaitable is rejected. If a type declaration is defined on + * the callable (ex: function (RuntimeException $exception) {}), then the function will only be called if the + * exception is an instance of the declared type of exception. * * @param callable<(Exception $exception): mixed)> $onRejected * @@ -72,22 +72,22 @@ public function delay($time); public function capture(callable $onRejected); /** - * Calls the given function with the value used to fulfill the promise, then fulfills the returned promise with - * the same value. If the promise is rejected, the returned promise is also rejected and $onFulfilled is not called. - * If $onFulfilled throws, the returned promise is rejected with the thrown exception. The return value of + * Calls the given function with the value used to fulfill the awaitable, then fulfills the returned awaitable with + * the same value. If the awaitable is rejected, the returned awaitable is also rejected and $onFulfilled is not + * called. If $onFulfilled throws, the returned awaitable is rejected with the thrown exception. The return value of * $onFulfilled is not used. * - * @param callable<(): Awaitable|null)> $onFulfilled + * @param callable<(mixed $value): Awaitable|null)> $onFulfilled * * @return \Icicle\Awaitable\Awaitable */ public function tap(callable $onFulfilled); /** - * The callback given to this function will be called if the promise is fulfilled or rejected. The callback is - * called with no arguments. If the callback does not throw, the returned promise is resolved in the same way as - * the original promise. That is, it is fulfilled or rejected with the same value or exception. If the callback - * throws an exception, the returned promise is rejected with that exception. + * The callback given to this function will be called if the awaitable is fulfilled or rejected. The callback is + * called with no arguments. If the callback does not throw, the returned awaitable is resolved in the same way as + * the original awaitable. That is, it is fulfilled or rejected with the same value or exception. If the callback + * throws an exception, the returned awaitable is rejected with that exception. * * @param callable<(): Awaitable|null)> $onResolved * @@ -96,10 +96,10 @@ public function tap(callable $onFulfilled); public function cleanup(callable $onResolved); /** - * If the promise returns an array or a Traversable object, this function uses the array (or array generated from + * If the awaitable returns an array or a Traversable object, this function uses the array (or array generated from * traversing the iterator) as arguments to the given function. The array is key sorted before being used as - * function arguments. If the promise does not return an array, the returned promise will be rejected with an - * \Icicle\Awaitable\Exception\TypeException. + * function arguments. If the awaitable does not return an array, the returned awaitable will be rejected with an + * \Icicle\Promise\Exception\UnexpectedTypeError. * * @param callable<(mixed ...$args): mixed> $onFulfilled * @@ -115,42 +115,42 @@ public function splat(callable $onFulfilled); public function uncancellable(); /** - * This function may be used to synchronously wait for a promise to be resolved. This function should generally - * not be used within a running event loop, but rather to set up a task (or set of tasks, then use join() or another + * This function may be used to synchronously wait for an awaitable to be resolved. This function should generally + * not be used within a running event loop, but rather to set up a task (or set of tasks, then use all() or another * function to group them) and synchronously wait for the task to complete. Using this function in a running event * loop will not block the loop, but it will prevent control from moving past the call to this function and disrupt * program flow. * - * @return mixed Promise fulfillment value. + * @return mixed Awaitable fulfillment value. * - * @throws \Icicle\Awaitable\Exception\UnresolvedError If the event loop empties without fulfilling the promise. - * @throws \Exception If the promise is rejected, the rejection reason is thrown from this function. + * @throws \Icicle\Awaitable\Exception\UnresolvedError If the event loop empties without fulfilling the awaitable. + * @throws \Exception If the awaitable is rejected, the rejection reason is thrown from this function. */ public function wait(); /** - * Returns true if the promise has not been resolved. + * Returns true if the awaitable has not been resolved. * * @return bool */ public function isPending(); /** - * Returns true if the promise has been fulfilled. + * Returns true if the awaitable has been fulfilled. * * @return bool */ public function isFulfilled(); /** - * Returns true if the promise has been rejected. + * Returns true if the awaitable has been rejected. * * @return bool */ public function isRejected(); /** - * Returns true if the promise has been cancelled. + * Returns true if the awaitable has been cancelled. * * @return bool */ diff --git a/src/Awaitable/Exception/InvalidResolverError.php b/src/Awaitable/Exception/InvalidResolverError.php index 8265729..5291d4f 100644 --- a/src/Awaitable/Exception/InvalidResolverError.php +++ b/src/Awaitable/Exception/InvalidResolverError.php @@ -9,4 +9,4 @@ namespace Icicle\Awaitable\Exception; -class InvalidResolverError extends Error {} +class InvalidResolverError extends InvalidArgumentError {} diff --git a/src/Awaitable/Exception/UnexpectedTypeError.php b/src/Awaitable/Exception/UnexpectedTypeError.php index 8845410..92ba31b 100644 --- a/src/Awaitable/Exception/UnexpectedTypeError.php +++ b/src/Awaitable/Exception/UnexpectedTypeError.php @@ -9,4 +9,4 @@ namespace Icicle\Awaitable\Exception; -class UnexpectedTypeError extends Error {} +class UnexpectedTypeError extends InvalidArgumentError {} diff --git a/src/Awaitable/Future.php b/src/Awaitable/Future.php index 06ebcba..a4d06c3 100644 --- a/src/Awaitable/Future.php +++ b/src/Awaitable/Future.php @@ -17,7 +17,9 @@ use Icicle\Loop; /** - * Awaitable implementation based on the Promises/A+ specification adding support for cancellation. + * Awaitable implementation based on the Promises/A+ specification adding support for cancellation. This class should + * be extended to create awaitable implementations. There is no way to externally resolve a Future, so the extending + * class must either use or expose the resolve() and reject() methods. * * @see http://promisesaplus.com */ diff --git a/src/Awaitable/Internal/AwaitableMethods.php b/src/Awaitable/Internal/AwaitableMethods.php index 92e3d0e..8467f2e 100644 --- a/src/Awaitable/Internal/AwaitableMethods.php +++ b/src/Awaitable/Internal/AwaitableMethods.php @@ -9,8 +9,8 @@ namespace Icicle\Awaitable\Internal; -use Icicle\Awaitable\Exception\UnexpectedTypeError; use Icicle\Awaitable\Awaitable; +use Icicle\Awaitable\Exception\UnexpectedTypeError; trait AwaitableMethods { diff --git a/src/Awaitable/Internal/FulfilledAwaitable.php b/src/Awaitable/Internal/FulfilledAwaitable.php index 6865507..86f5ef1 100644 --- a/src/Awaitable/Internal/FulfilledAwaitable.php +++ b/src/Awaitable/Internal/FulfilledAwaitable.php @@ -23,7 +23,7 @@ class FulfilledAwaitable extends ResolvedAwaitable private $value; /** - * @param mixed $value Anything other than a Awaitable object. + * @param mixed $value Anything other than an Awaitable object. * * @throws \Icicle\Awaitable\Exception\InvalidArgumentError If an awaitable is given as the value. */ diff --git a/src/Awaitable/Promise.php b/src/Awaitable/Promise.php index 3fd1c84..ffab1e5 100644 --- a/src/Awaitable/Promise.php +++ b/src/Awaitable/Promise.php @@ -12,14 +12,15 @@ use Icicle\Awaitable\Exception\InvalidResolverError; /** - * Promise implementation based on the Promises/A+ specification adding support for cancellation. - * - * @see http://promisesaplus.com + * A Promise is an awaitable that provides the functions to resolve or reject the promise to the resolver function + * given to the constructor. A Promise cannot be externally resolved. Only the functions provided to the constructor + * may resolve the Promise. The cancellation function should be returned from the resolver function (or null if no + * cancellation function is needed). */ final class Promise extends Future { /** - * @param callable<(callable $resolve, callable $reject, Loop $loop): callable|null> $resolver + * @param callable<(callable $resolve, callable $reject): callable|null> $resolver */ public function __construct(callable $resolver) { @@ -50,7 +51,7 @@ public function __construct(callable $resolver) parent::__construct($onCancelled); } catch (\Exception $exception) { parent::__construct(); - $reject($exception); + $this->reject($exception); } } } diff --git a/tests/Awaitable/Internal/DoneQueueTest.php b/tests/Awaitable/Internal/DoneQueueTest.php index 8d3de32..4edbf77 100644 --- a/tests/Awaitable/Internal/DoneQueueTest.php +++ b/tests/Awaitable/Internal/DoneQueueTest.php @@ -12,9 +12,6 @@ use Icicle\Awaitable\Internal\DoneQueue; use Icicle\Tests\TestCase; -/** - * @requires PHP 5.4 - */ class DoneQueueTest extends TestCase { public function testInvoke() diff --git a/tests/Awaitable/Internal/FulfilledAwaitableTest.php b/tests/Awaitable/Internal/FulfilledAwaitableTest.php index f216c26..770c080 100644 --- a/tests/Awaitable/Internal/FulfilledAwaitableTest.php +++ b/tests/Awaitable/Internal/FulfilledAwaitableTest.php @@ -15,8 +15,6 @@ /** * Tests the constructor only. All other methods are covered by PromiseTest. - * - * @requires PHP 5.4 */ class FulfilledAwaitableTest extends TestCase {