From 7b3b87d4c76c1353a165219fb174610834cd61d3 Mon Sep 17 00:00:00 2001 From: Joe Watkins Date: Fri, 30 Dec 2016 15:00:55 +0000 Subject: [PATCH 1/7] rewording of readme and docblock --- README.md | 30 ++++++++---------------------- src/Promise.php | 7 +------ 2 files changed, 9 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 0bb253d..8618a3f 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,18 @@ # Promise -The purpose of this specification is to provide a common interface for simple placeholder objects returned from async operations. This allows libraries and components from different vendors to create coroutines regardless of the used placeholder implementation. This specification is not designed to replace promise implementations that may be chained. Instead, this interface may be extended by promise implementations. +The purpose of this specification is to provide a common interface for simple placeholder objects returned from async operations. This allows libraries and components from different vendors to create coroutines regardless of the placeholder implementation used. This specification is not designed to replace promise implementations that may be chained. Instead, the common interface may be extended by promise implementations. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119][]. -A `Promise` represents the eventual result of an asynchronous operation. Interaction with a `Promise` happens through its `when()` method, which registers a callback to receive either a `Promise`'s eventual value or the reason why the `Promise` has failed. +A `Promise` represents the eventual result of an asynchronous operation. Interaction with a `Promise` happens through its `when()` method, which registers a callback to receive either a `Promise`'s eventual value, or reason for failure. `Promise` is the fundamental primitive in asynchronous programming. It should be as lightweight as possible, as any cost adds up significantly. -This specification defines the absolute minimums for interoperable coroutines, which can be implemented in PHP using generators. +This specification defines the absolute minimum for interoperable coroutines, which can be implemented in PHP using generators. -This specification does not deal with how to create, succeed or fail `Promise`s, as only the consumption of `Promise`s is required to be interoperable. +This specification does not deal with how a `Promise` should be created, succeed, or fail, as only the consumption of `Promise` is required to be interoperable. For further design explanations and notes, please refer to [the meta document](META.md). @@ -39,7 +39,7 @@ A `Promise` is resolved once it either succeeded or failed. ## Consumption -A `Promise` MUST implement `AsyncInterop\Promise` and thus provide a `when()` method to access its current or eventual value or reason. +A `Promise` MUST implement `AsyncInterop\Promise` and thus provide a `when()` method to access its value or reason. ```php * * @return void */ @@ -69,20 +64,11 @@ interface Promise } ``` -The `when()` method MUST accept at least one argument: - -`$callback` – A callable conforming to the following signature: - -```php -function($error, $value) { /* ... */ } -``` - -Any implementation MUST at least provide these two parameters. The implementation MAY extend the `Promise` interface with additional parameters passed to the callback. Further arguments to `when()` MUST have default values, so `when()` can always be called with only one argument. `when()` MAY NOT return a value. `when()` MUST NOT throw exceptions bubbling up from a callback invocation. +The implementation MAY extend `Promise::when` with additional parameters passed to the callback. Further arguments to `Promise::when()` MUST have default values, so `Promise::when()` can always be called with only one argument. `Promise::when()` MAY NOT return a value. `Promise::when()` MUST NOT throw exceptions bubbling up from a callback invocation. -> **NOTE:** The signature doesn't specify a type for `$error`. This is due to the new `Throwable` interface introduced in PHP 7. As this specification is PHP 5 compatible, we can use neither `Throwable` nor `Exception`. +All callbacks registered before the resolution MUST be executed in the order they were registered. Callbacks registered after the resolution MUST be executed immediately. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `Interop\Async\Promise\ErrorHandler::notify`. The `Promise` MUST then continue to call the remaining callbacks with the original parameters. All callbacks registered before the resolution MUST be executed in the order they were registered. Callbacks registered after the resolution MUST be executed immediately. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `AsyncInterop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters. - Registered callbacks MUST NOT be called from a file with strict types enabled (`declare(strict_types=1)`). ## Contributors diff --git a/src/Promise.php b/src/Promise.php index 2b69124..0b4a862 100644 --- a/src/Promise.php +++ b/src/Promise.php @@ -10,14 +10,9 @@ interface Promise /** * Registers a callback to be invoked when the promise is resolved. * - * The callback receives `null` as first parameter and `$value` as second parameter on success. It receives the - * failure reason as first parameter and `null` as second parameter on failure. - * * If the promise is already resolved, the callback MUST be executed immediately. * - * Warning: If you use type declarations for `$value`, be sure to make them accept `null` in case of failures. - * - * @param callable(\Throwable|\Exception|null $exception, mixed $value) $onResolved Callback to be executed. + * @param callable(mixed $reason, mixed $value) <`$reason` shall be `null` on success, `$value` shall be `null` on failure> * * @return void */ From ac187c11afcdab79562c08018905f4861d4b0112 Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Sat, 31 Dec 2016 21:15:36 +0100 Subject: [PATCH 2/7] Adjust PHPDoc to match the rest of async-interop --- README.md | 3 ++- src/Promise.php | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8618a3f..bee73e8 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,8 @@ interface Promise * * If the promise is already resolved, the callback MUST be executed immediately. * - * @param callable(mixed $reason, mixed $value) <`$reason` shall be `null` on success, `$value` shall be `null` on failure> + * @param callable(mixed $reason, mixed $value) @onResolved `$reason` shall be `null` on success, `$value` shall be + * `null` on failure. * * @return void */ diff --git a/src/Promise.php b/src/Promise.php index 0b4a862..514f408 100644 --- a/src/Promise.php +++ b/src/Promise.php @@ -12,7 +12,8 @@ interface Promise * * If the promise is already resolved, the callback MUST be executed immediately. * - * @param callable(mixed $reason, mixed $value) <`$reason` shall be `null` on success, `$value` shall be `null` on failure> + * @param callable(mixed $reason, mixed $value) @onResolved `$reason` shall be `null` on success, `$value` shall be + * `null` on failure. * * @return void */ From 656e89769f93d2e0955e688c6ab0ed2b1531d683 Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Thu, 5 Jan 2017 19:04:21 +0100 Subject: [PATCH 3/7] Fix rebase fail --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index bee73e8..6df533a 100644 --- a/README.md +++ b/README.md @@ -67,8 +67,6 @@ interface Promise The implementation MAY extend `Promise::when` with additional parameters passed to the callback. Further arguments to `Promise::when()` MUST have default values, so `Promise::when()` can always be called with only one argument. `Promise::when()` MAY NOT return a value. `Promise::when()` MUST NOT throw exceptions bubbling up from a callback invocation. -All callbacks registered before the resolution MUST be executed in the order they were registered. Callbacks registered after the resolution MUST be executed immediately. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `Interop\Async\Promise\ErrorHandler::notify`. The `Promise` MUST then continue to call the remaining callbacks with the original parameters. - All callbacks registered before the resolution MUST be executed in the order they were registered. Callbacks registered after the resolution MUST be executed immediately. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `AsyncInterop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters. Registered callbacks MUST NOT be called from a file with strict types enabled (`declare(strict_types=1)`). From 4cefae561800638dea076884506a080d26ab938f Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Thu, 5 Jan 2017 19:06:26 +0100 Subject: [PATCH 4/7] Improve wording for when to call when callbacks --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6df533a..33587b8 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,10 @@ interface Promise The implementation MAY extend `Promise::when` with additional parameters passed to the callback. Further arguments to `Promise::when()` MUST have default values, so `Promise::when()` can always be called with only one argument. `Promise::when()` MAY NOT return a value. `Promise::when()` MUST NOT throw exceptions bubbling up from a callback invocation. -All callbacks registered before the resolution MUST be executed in the order they were registered. Callbacks registered after the resolution MUST be executed immediately. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `AsyncInterop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters. +All callbacks registered before the `Promise` is resolved MUST be executed in the order they were registered after the `Promise` has been resolved. Callbacks registered after the resolution MUST be executed immediately. + +If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `AsyncInterop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters. + Registered callbacks MUST NOT be called from a file with strict types enabled (`declare(strict_types=1)`). ## Contributors From 1c4c2d90083782d50f7372c747fe4d8920eaff22 Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Thu, 5 Jan 2017 19:07:22 +0100 Subject: [PATCH 5/7] Add missing parens --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 33587b8..93cbbeb 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ interface Promise } ``` -The implementation MAY extend `Promise::when` with additional parameters passed to the callback. Further arguments to `Promise::when()` MUST have default values, so `Promise::when()` can always be called with only one argument. `Promise::when()` MAY NOT return a value. `Promise::when()` MUST NOT throw exceptions bubbling up from a callback invocation. +The implementation MAY extend `Promise::when()` with additional parameters passed to the callback. Further arguments to `Promise::when()` MUST have default values, so `Promise::when()` can always be called with only one argument. `Promise::when()` MAY NOT return a value. `Promise::when()` MUST NOT throw exceptions bubbling up from a callback invocation. All callbacks registered before the `Promise` is resolved MUST be executed in the order they were registered after the `Promise` has been resolved. Callbacks registered after the resolution MUST be executed immediately. From a55d38600f71d58ded0210fe224648be051bcca8 Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Thu, 5 Jan 2017 21:18:35 +0100 Subject: [PATCH 6/7] Allow implementations to return values by leaving it unspecified, revert callable docs --- README.md | 10 ++++------ src/Promise.php | 8 ++++---- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 93cbbeb..12d8a2c 100644 --- a/README.md +++ b/README.md @@ -56,20 +56,18 @@ interface Promise * * If the promise is already resolved, the callback MUST be executed immediately. * - * @param callable(mixed $reason, mixed $value) @onResolved `$reason` shall be `null` on success, `$value` shall be - * `null` on failure. + * @param callable(\Throwable|\Exception|null $exception, mixed $value) @onResolved `$reason` shall be `null` on + * success, `$value` shall be `null` on failure. * - * @return void + * @return mixed Return type and value are unspecified. */ public function when(callable $onResolved); } ``` -The implementation MAY extend `Promise::when()` with additional parameters passed to the callback. Further arguments to `Promise::when()` MUST have default values, so `Promise::when()` can always be called with only one argument. `Promise::when()` MAY NOT return a value. `Promise::when()` MUST NOT throw exceptions bubbling up from a callback invocation. - All callbacks registered before the `Promise` is resolved MUST be executed in the order they were registered after the `Promise` has been resolved. Callbacks registered after the resolution MUST be executed immediately. -If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `AsyncInterop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters. +The invocation of `Promise::when()` MUST NOT throw exceptions bubbling up from a `$onResolved` invocation. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `AsyncInterop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters. Registered callbacks MUST NOT be called from a file with strict types enabled (`declare(strict_types=1)`). diff --git a/src/Promise.php b/src/Promise.php index 514f408..065e046 100644 --- a/src/Promise.php +++ b/src/Promise.php @@ -12,10 +12,10 @@ interface Promise * * If the promise is already resolved, the callback MUST be executed immediately. * - * @param callable(mixed $reason, mixed $value) @onResolved `$reason` shall be `null` on success, `$value` shall be - * `null` on failure. + * @param callable(\Throwable|\Exception|null $exception, mixed $value) @onResolved `$reason` shall be `null` on + * success, `$value` shall be `null` on failure. * - * @return void + * @return mixed Return type and value are unspecified. */ public function when(callable $onResolved); -} +} \ No newline at end of file From 72a08e582535774639097c6f2e04da86ddc4bcea Mon Sep 17 00:00:00 2001 From: Bob Weinand Date: Thu, 5 Jan 2017 22:24:58 +0100 Subject: [PATCH 7/7] Remove unnecessary mixed from declaration --- README.md | 2 +- src/Promise.php | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 12d8a2c..12a35b1 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ interface Promise * * If the promise is already resolved, the callback MUST be executed immediately. * - * @param callable(\Throwable|\Exception|null $exception, mixed $value) @onResolved `$reason` shall be `null` on + * @param callable(\Throwable|\Exception|null $exception, $value) @onResolved `$reason` shall be `null` on * success, `$value` shall be `null` on failure. * * @return mixed Return type and value are unspecified. diff --git a/src/Promise.php b/src/Promise.php index 065e046..8c0d9c3 100644 --- a/src/Promise.php +++ b/src/Promise.php @@ -12,10 +12,10 @@ interface Promise * * If the promise is already resolved, the callback MUST be executed immediately. * - * @param callable(\Throwable|\Exception|null $exception, mixed $value) @onResolved `$reason` shall be `null` on + * @param callable(\Throwable|\Exception|null $exception, $value) @onResolved `$reason` shall be `null` on * success, `$value` shall be `null` on failure. * * @return mixed Return type and value are unspecified. */ public function when(callable $onResolved); -} \ No newline at end of file +}