Skip to content

Commit 511ae43

Browse files
authored
Merge pull request #35 from async-interop/krakjoe-rewording
Rewording of README and docblock
2 parents 5cc82dd + 72a08e5 commit 511ae43

File tree

2 files changed

+13
-31
lines changed

2 files changed

+13
-31
lines changed

README.md

Lines changed: 10 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
# Promise
22

3-
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.
3+
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.
44

55
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
66
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
77
interpreted as described in [RFC 2119][].
88

9-
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.
9+
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.
1010

1111
`Promise` is the fundamental primitive in asynchronous programming. It should be as lightweight as possible, as any cost adds up significantly.
1212

13-
This specification defines the absolute minimums for interoperable coroutines, which can be implemented in PHP using generators.
13+
This specification defines the absolute minimum for interoperable coroutines, which can be implemented in PHP using generators.
1414

15-
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.
15+
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.
1616

1717
For further design explanations and notes, please refer to [the meta document](META.md).
1818

@@ -39,7 +39,7 @@ A `Promise` is resolved once it either succeeded or failed.
3939

4040
## Consumption
4141

42-
A `Promise` MUST implement `AsyncInterop\Promise` and thus provide a `when()` method to access its current or eventual value or reason.
42+
A `Promise` MUST implement `AsyncInterop\Promise` and thus provide a `when()` method to access its value or reason.
4343

4444
```php
4545
<?php
@@ -54,34 +54,20 @@ interface Promise
5454
/**
5555
* Registers a callback to be invoked when the promise is resolved.
5656
*
57-
* The callback receives `null` as first parameter and `$value` as second parameter on success. It receives the
58-
* failure reason as first parameter and `null` as second parameter on failure.
59-
*
6057
* If the promise is already resolved, the callback MUST be executed immediately.
6158
*
62-
* Warning: If you use type declarations for `$value`, be sure to make them accept `null` in case of failures.
63-
*
64-
* @param callable(\Throwable|\Exception|null $exception, mixed $value) $onResolved Callback to be executed.
59+
* @param callable(\Throwable|\Exception|null $exception, $value) @onResolved `$reason` shall be `null` on
60+
* success, `$value` shall be `null` on failure.
6561
*
66-
* @return void
62+
* @return mixed Return type and value are unspecified.
6763
*/
6864
public function when(callable $onResolved);
6965
}
7066
```
7167

72-
The `when()` method MUST accept at least one argument:
73-
74-
`$callback` – A callable conforming to the following signature:
75-
76-
```php
77-
function($error, $value) { /* ... */ }
78-
```
79-
80-
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.
81-
82-
> **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`.
68+
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.
8369

84-
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.
70+
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.
8571

8672
Registered callbacks MUST NOT be called from a file with strict types enabled (`declare(strict_types=1)`).
8773

src/Promise.php

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,12 @@ interface Promise
1010
/**
1111
* Registers a callback to be invoked when the promise is resolved.
1212
*
13-
* The callback receives `null` as first parameter and `$value` as second parameter on success. It receives the
14-
* failure reason as first parameter and `null` as second parameter on failure.
15-
*
1613
* If the promise is already resolved, the callback MUST be executed immediately.
1714
*
18-
* Warning: If you use type declarations for `$value`, be sure to make them accept `null` in case of failures.
19-
*
20-
* @param callable(\Throwable|\Exception|null $exception, mixed $value) $onResolved Callback to be executed.
15+
* @param callable(\Throwable|\Exception|null $exception, $value) @onResolved `$reason` shall be `null` on
16+
* success, `$value` shall be `null` on failure.
2117
*
22-
* @return void
18+
* @return mixed Return type and value are unspecified.
2319
*/
2420
public function when(callable $onResolved);
2521
}

0 commit comments

Comments
 (0)