4
use GuzzleHttp\Event\BeforeEvent;
5
use GuzzleHttp\Event\RequestEvents;
6
use GuzzleHttp\Message\RequestInterface;
7
use GuzzleHttp\Message\ResponseInterface;
8
use GuzzleHttp\Ring\Core;
9
use GuzzleHttp\Ring\Future\FutureInterface;
10
use GuzzleHttp\Event\ListenerAttacherTrait;
11
use GuzzleHttp\Event\EndEvent;
12
use React\Promise\Deferred;
13
use React\Promise\FulfilledPromise;
14
use React\Promise\PromiseInterface;
15
use React\Promise\RejectedPromise;
18
* Sends and iterator of requests concurrently using a capped pool size.
20
* The Pool object implements FutureInterface, meaning it can be used later
21
* when necessary, the requests provided to the pool can be cancelled, and
22
* you can check the state of the pool to know if it has been dereferenced
23
* (sent) or has been cancelled.
25
* When sending the pool, keep in mind that no results are returned: callers
26
* are expected to handle results asynchronously using Guzzle's event system.
27
* When requests complete, more are added to the pool to ensure that the
28
* requested pool size is always filled as much as possible.
30
* IMPORTANT: Do not provide a pool size greater that what the utilized
31
* underlying RingPHP handler can support. This will result is extremely poor
34
class Pool implements FutureInterface
36
use ListenerAttacherTrait;
38
/** @var \GuzzleHttp\ClientInterface */
41
/** @var \Iterator Yields requests */
47
/** @var PromiseInterface */
50
private $waitQueue = [];
51
private $eventListeners = [];
53
private $isRealized = false;
56
* The option values for 'before', 'complete', 'error' and 'end' can be a
57
* callable, an associative array containing event data, or an array of
58
* event data arrays. Event data arrays contain the following keys:
60
* - fn: callable to invoke that receives the event
61
* - priority: Optional event priority (defaults to 0)
62
* - once: Set to true so that the event is removed after it is triggered
64
* @param ClientInterface $client Client used to send the requests.
65
* @param array|\Iterator $requests Requests to send in parallel
66
* @param array $options Associative array of options
67
* - pool_size: (callable|int) Maximum number of requests to send
68
* concurrently, or a callback that receives
69
* the current queue size and returns the
70
* number of new requests to send
71
* - before: (callable|array) Receives a BeforeEvent
72
* - complete: (callable|array) Receives a CompleteEvent
73
* - error: (callable|array) Receives a ErrorEvent
74
* - end: (callable|array) Receives an EndEvent
76
public function __construct(
77
ClientInterface $client,
81
$this->client = $client;
82
$this->iter = $this->coerceIterable($requests);
83
$this->deferred = new Deferred();
84
$this->promise = $this->deferred->promise();
85
$this->poolSize = isset($options['pool_size'])
86
? $options['pool_size'] : 25;
87
$this->eventListeners = $this->prepareListeners(
89
['before', 'complete', 'error', 'end']
94
* Sends multiple requests in parallel and returns an array of responses
95
* and exceptions that uses the same ordering as the provided requests.
97
* IMPORTANT: This method keeps every request and response in memory, and
98
* as such, is NOT recommended when sending a large number or an
99
* indeterminate number of requests concurrently.
101
* @param ClientInterface $client Client used to send the requests
102
* @param array|\Iterator $requests Requests to send in parallel
103
* @param array $options Passes through the options available in
104
* {@see GuzzleHttp\Pool::__construct}
106
* @return BatchResults Returns a container for the results.
107
* @throws \InvalidArgumentException if the event format is incorrect.
109
public static function batch(
110
ClientInterface $client,
114
$hash = new \SplObjectStorage();
115
foreach ($requests as $request) {
116
$hash->attach($request);
119
// In addition to the normally run events when requests complete, add
120
// and event to continuously track the results of transfers in the hash.
121
(new self($client, $requests, RequestEvents::convertEventArray(
125
'priority' => RequestEvents::LATE,
126
'fn' => function (EndEvent $e) use ($hash) {
127
$hash[$e->getRequest()] = $e->getException()
134
return new BatchResults($hash);
138
* Creates a Pool and immediately sends the requests.
140
* @param ClientInterface $client Client used to send the requests
141
* @param array|\Iterator $requests Requests to send in parallel
142
* @param array $options Passes through the options available in
143
* {@see GuzzleHttp\Pool::__construct}
145
public static function send(
146
ClientInterface $client,
150
$pool = new self($client, $requests, $options);
154
private function getPoolSize()
156
return is_callable($this->poolSize)
157
? call_user_func($this->poolSize, count($this->waitQueue))
162
* Add as many requests as possible up to the current pool limit.
164
private function addNextRequests()
166
$limit = max($this->getPoolSize() - count($this->waitQueue), 0);
168
if (!$this->addNextRequest()) {
174
public function wait()
176
if ($this->isRealized) {
180
// Seed the pool with N number of requests.
181
$this->addNextRequests();
183
// Stop if the pool was cancelled while transferring requests.
184
if ($this->isRealized) {
188
// Wait on any outstanding FutureResponse objects.
189
while ($response = array_pop($this->waitQueue)) {
192
} catch (\Exception $e) {
193
// Eat exceptions because they should be handled asynchronously
195
$this->addNextRequests();
198
// Clean up no longer needed state.
199
$this->isRealized = true;
200
$this->waitQueue = $this->eventListeners = [];
201
$this->client = $this->iter = null;
202
$this->deferred->resolve(true);
210
* Attempt to cancel all outstanding requests (requests that are queued for
211
* dereferencing). Returns true if all outstanding requests can be
216
public function cancel()
218
if ($this->isRealized) {
222
$success = $this->isRealized = true;
223
foreach ($this->waitQueue as $response) {
224
if (!$response->cancel()) {
233
* Returns a promise that is invoked when the pool completed. There will be
238
public function then(
239
callable $onFulfilled = null,
240
callable $onRejected = null,
241
callable $onProgress = null
243
return $this->promise->then($onFulfilled, $onRejected, $onProgress);
246
public function promise()
248
return $this->promise;
251
private function coerceIterable($requests)
253
if ($requests instanceof \Iterator) {
255
} elseif (is_array($requests)) {
256
return new \ArrayIterator($requests);
259
throw new \InvalidArgumentException('Expected Iterator or array. '
260
. 'Found ' . Core::describeType($requests));
264
* Adds the next request to pool and tracks what requests need to be
265
* dereferenced when completing the pool.
267
private function addNextRequest()
271
if ($this->isRealized || !$this->iter || !$this->iter->valid()) {
275
$request = $this->iter->current();
278
if (!($request instanceof RequestInterface)) {
279
throw new \InvalidArgumentException(sprintf(
280
'All requests in the provided iterator must implement '
281
. 'RequestInterface. Found %s',
282
Core::describeType($request)
286
// Be sure to use "lazy" futures, meaning they do not send right away.
287
$request->getConfig()->set('future', 'lazy');
288
$hash = spl_object_hash($request);
289
$this->attachListeners($request, $this->eventListeners);
290
$request->getEmitter()->on('before', [$this, '_trackRetries'], RequestEvents::EARLY);
291
$response = $this->client->send($request);
292
$this->waitQueue[$hash] = $response;
293
$promise = $response->promise();
295
// Don't recursively call itself for completed or rejected responses.
296
if ($promise instanceof FulfilledPromise
297
|| $promise instanceof RejectedPromise
300
$this->finishResponse($request, $response->wait(), $hash);
301
} catch (\Exception $e) {
302
$this->finishResponse($request, $e, $hash);
307
// Use this function for both resolution and rejection.
308
$thenFn = function ($value) use ($request, $hash) {
309
$this->finishResponse($request, $value, $hash);
310
if (!$request->getConfig()->get('_pool_retries')) {
311
$this->addNextRequests();
315
$promise->then($thenFn, $thenFn);
320
public function _trackRetries(BeforeEvent $e)
322
$e->getRequest()->getConfig()->set('_pool_retries', $e->getRetryCount());
325
private function finishResponse($request, $value, $hash)
327
unset($this->waitQueue[$hash]);
328
$result = $value instanceof ResponseInterface
329
? ['request' => $request, 'response' => $value, 'error' => null]
330
: ['request' => $request, 'response' => null, 'error' => $value];
331
$this->deferred->notify($result);