mirror of
https://github.com/danog/amp.git
synced 2024-12-11 17:09:40 +01:00
75 lines
2.6 KiB
Markdown
75 lines
2.6 KiB
Markdown
# Promise Combinators
|
|
|
|
Multiple promises can be combined into a single promise using different functions.
|
|
|
|
## `all()`
|
|
|
|
`Amp\Promise\all()` combines an array of promise objects into a single promise that will resolve
|
|
when all promises in the group resolve. If any one of the `Amp\Promise` instances fails the
|
|
combinator's `Promise` will fail. Otherwise the resulting `Promise` succeeds with an array matching
|
|
keys from the input array to their resolved values.
|
|
|
|
The `all()` combinator is extremely powerful because it allows us to concurrently execute many
|
|
asynchronous operations at the same time. Let's look at a simple example using the Amp HTTP client
|
|
([Artax](https://github.com/amphp/artax)) to retrieve multiple HTTP resources concurrently:
|
|
|
|
```php
|
|
<?php
|
|
|
|
use Amp\Loop;
|
|
use function Amp\Promise;
|
|
|
|
Loop::run(function () {
|
|
$httpClient = new Amp\Artax\Client;
|
|
$promiseArray = $httpClient->requestMulti([
|
|
"google" => "http://www.google.com",
|
|
"news" => "http://news.google.com",
|
|
"bing" => "http://www.bing.com",
|
|
"yahoo" => "https://www.yahoo.com",
|
|
]);
|
|
|
|
try {
|
|
// magic combinator sauce to flatten the promise
|
|
// array into a single promise
|
|
$responses = yield Promise\all($promiseArray);
|
|
|
|
foreach ($responses as $key => $response) {
|
|
printf(
|
|
"%s | HTTP/%s %d %s\n",
|
|
$key,
|
|
$response->getProtocol(),
|
|
$response->getStatus(),
|
|
$response->getReason()
|
|
);
|
|
}
|
|
} catch (Amp\MultiReasonException $e) {
|
|
// If any one of the requests fails the combo
|
|
// promise returned by Amp\all() will fail and
|
|
// be thrown back into our generator here.
|
|
echo $e->getMessage(), "\n";
|
|
}
|
|
|
|
Loop::stop();
|
|
});
|
|
```
|
|
|
|
### `some()`
|
|
|
|
`Amp\Promise\some()` is the same as `all()` except that it tolerates individual failures. As long
|
|
as at least one promise in the passed succeeds, the combined promise will succeed. The successful
|
|
resolution value is an array of the form `[$arrayOfErrors, $arrayOfValues]`. The individual keys
|
|
in the component arrays are preserved from the promise array passed to the functor for evaluation.
|
|
|
|
### `any()`
|
|
|
|
`Amp\Promise\any()` is the same as `some()` except that it tolerates all failures. It will succeed even if all promises failed.
|
|
|
|
### `first()`
|
|
|
|
`Amp\Promise\first()` resolves with the first successful result. The resulting promise will only fail if all
|
|
promises in the group fail or if the promise array is empty.
|
|
|
|
## Further Reading
|
|
|
|
* [Other Promise Helpers](./miscellaneous.md)
|