Debian Codegraph @

vendor/clue/mq-react/src/Queue.php

raw
1 <?php
2
3 namespace Clue\React\Mq;
4
5 use React\Promise;
6 use React\Promise\Deferred;
7 use React\Promise\PromiseInterface;
8
9 /**
10 * The `Queue` is responsible for managing your operations and ensuring not too
11 * many operations are executed at once. It's a very simple and lightweight
12 * in-memory implementation of the
13 * [leaky bucket](https://en.wikipedia.org/wiki/Leaky_bucket#As_a_queue) algorithm.
14 *
15 * This means that you control how many operations can be executed concurrently.
16 * If you add a job to the queue and it still below the limit, it will be executed
17 * immediately. If you keep adding new jobs to the queue and its concurrency limit
18 * is reached, it will not start a new operation and instead queue this for future
19 * execution. Once one of the pending operations complete, it will pick the next
20 * job from the queue and execute this operation.
21 *
22 * @template T
23 */
24 class Queue implements \Countable
25 {
26 private $concurrency;
27 private $limit;
28 private $handler;
29
30 /** @var int<0,max> */
31 private $pending = 0;
32
33 /** @var array<int,\Closure():void> */
34 private $queue = array();
35
36 /**
37 * Concurrently process all given jobs through the given `$handler`.
38 *
39 * This is a convenience method which uses the `Queue` internally to
40 * schedule all jobs while limiting concurrency to ensure no more than
41 * `$concurrency` jobs ever run at once. It will return a promise which
42 * resolves with the results of all jobs on success.
43 *
44 * ```php
45 * $browser = new React\Http\Browser();
46 *
47 * $promise = Queue::all(3, $urls, function ($url) use ($browser) {
48 * return $browser->get($url);
49 * });
50 *
51 * $promise->then(function (array $responses) {
52 * echo 'All ' . count($responses) . ' successful!' . PHP_EOL;
53 * });
54 * ```
55 *
56 * If either of the jobs fail, it will reject the resulting promise and will
57 * try to cancel all outstanding jobs. Similarly, calling `cancel()` on the
58 * resulting promise will try to cancel all outstanding jobs. See
59 * [promises](#promises) and [cancellation](#cancellation) for details.
60 *
61 * The `$concurrency` parameter sets a new soft limit for the maximum number
62 * of jobs to handle concurrently. Finding a good concurrency limit depends
63 * on your particular use case. It's common to limit concurrency to a rather
64 * small value, as doing more than a dozen of things at once may easily
65 * overwhelm the receiving side. Using a `1` value will ensure that all jobs
66 * are processed one after another, effectively creating a "waterfall" of
67 * jobs. Using a value less than 1 will reject with an
68 * `InvalidArgumentException` without processing any jobs.
69 *
70 * ```php
71 * // handle up to 10 jobs concurrently
72 * $promise = Queue::all(10, $jobs, $handler);
73 * ```
74 *
75 * ```php
76 * // handle each job after another without concurrency (waterfall)
77 * $promise = Queue::all(1, $jobs, $handler);
78 * ```
79 *
80 * The `$jobs` parameter must be an array with all jobs to process. Each
81 * value in this array will be passed to the `$handler` to start one job.
82 * The array keys will be preserved in the resulting array, while the array
83 * values will be replaced with the job results as returned by the
84 * `$handler`. If this array is empty, this method will resolve with an
85 * empty array without processing any jobs.
86 *
87 * The `$handler` parameter must be a valid callable that accepts your job
88 * parameters, invokes the appropriate operation and returns a Promise as a
89 * placeholder for its future result. If the given argument is not a valid
90 * callable, this method will reject with an `InvalidArgumentException`
91 * without processing any jobs.
92 *
93 * ```php
94 * // using a Closure as handler is usually recommended
95 * $promise = Queue::all(10, $jobs, function ($url) use ($browser) {
96 * return $browser->get($url);
97 * });
98 * ```
99 *
100 * ```php
101 * // accepts any callable, so PHP's array notation is also supported
102 * $promise = Queue::all(10, $jobs, array($browser, 'get'));
103 * ```
104 *
105 * > Keep in mind that returning an array of response messages means that
106 * the whole response body has to be kept in memory.
107 *
108 * @template TKey
109 * @template TIn
110 * @template TOut
111 * @param int $concurrency concurrency soft limit
112 * @param array<TKey,TIn> $jobs
113 * @param callable(TIn):PromiseInterface<TOut> $handler
114 * @return PromiseInterface<array<TKey,TOut>> Returns a Promise which resolves with an array of all resolution values
115 * or rejects when any of the operations reject.
116 */
117 public static function all($concurrency, array $jobs, $handler)
118 {
119 try {
120 // limit number of concurrent operations
121 $q = new self($concurrency, null, $handler);
122 } catch (\InvalidArgumentException $e) {
123 // reject if $concurrency or $handler is invalid
124 return Promise\reject($e);
125 }
126
127 // try invoking all operations and automatically queue excessive ones
128 $promises = array_map($q, $jobs);
129
130 return new Promise\Promise(function ($resolve, $reject) use ($promises) {
131 Promise\all($promises)->then($resolve, function ($e) use ($promises, $reject) {
132 // cancel all pending promises if a single promise fails
133 foreach (array_reverse($promises) as $promise) {
134 if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
135 $promise->cancel();
136 }
137 }
138
139 // reject with original rejection message
140 $reject($e);
141 });
142 }, function () use ($promises) {
143 // cancel all pending promises on cancellation
144 foreach (array_reverse($promises) as $promise) {
145 if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
146 $promise->cancel();
147 }
148 }
149 });
150 }
151
152 /**
153 * Concurrently process the given jobs through the given `$handler` and
154 * resolve with first resolution value.
155 *
156 * This is a convenience method which uses the `Queue` internally to
157 * schedule all jobs while limiting concurrency to ensure no more than
158 * `$concurrency` jobs ever run at once. It will return a promise which
159 * resolves with the result of the first job on success and will then try
160 * to `cancel()` all outstanding jobs.
161 *
162 * ```php
163 * $browser = new React\Http\Browser();
164 *
165 * $promise = Queue::any(3, $urls, function ($url) use ($browser) {
166 * return $browser->get($url);
167 * });
168 *
169 * $promise->then(function (ResponseInterface $response) {
170 * echo 'First response: ' . $response->getBody() . PHP_EOL;
171 * });
172 * ```
173 *
174 * If all of the jobs fail, it will reject the resulting promise. Similarly,
175 * calling `cancel()` on the resulting promise will try to cancel all
176 * outstanding jobs. See [promises](#promises) and
177 * [cancellation](#cancellation) for details.
178 *
179 * The `$concurrency` parameter sets a new soft limit for the maximum number
180 * of jobs to handle concurrently. Finding a good concurrency limit depends
181 * on your particular use case. It's common to limit concurrency to a rather
182 * small value, as doing more than a dozen of things at once may easily
183 * overwhelm the receiving side. Using a `1` value will ensure that all jobs
184 * are processed one after another, effectively creating a "waterfall" of
185 * jobs. Using a value less than 1 will reject with an
186 * `InvalidArgumentException` without processing any jobs.
187 *
188 * ```php
189 * // handle up to 10 jobs concurrently
190 * $promise = Queue::any(10, $jobs, $handler);
191 * ```
192 *
193 * ```php
194 * // handle each job after another without concurrency (waterfall)
195 * $promise = Queue::any(1, $jobs, $handler);
196 * ```
197 *
198 * The `$jobs` parameter must be an array with all jobs to process. Each
199 * value in this array will be passed to the `$handler` to start one job.
200 * The array keys have no effect, the promise will simply resolve with the
201 * job results of the first successful job as returned by the `$handler`.
202 * If this array is empty, this method will reject without processing any
203 * jobs.
204 *
205 * The `$handler` parameter must be a valid callable that accepts your job
206 * parameters, invokes the appropriate operation and returns a Promise as a
207 * placeholder for its future result. If the given argument is not a valid
208 * callable, this method will reject with an `InvalidArgumentExceptionn`
209 * without processing any jobs.
210 *
211 * ```php
212 * // using a Closure as handler is usually recommended
213 * $promise = Queue::any(10, $jobs, function ($url) use ($browser) {
214 * return $browser->get($url);
215 * });
216 * ```
217 *
218 * ```php
219 * // accepts any callable, so PHP's array notation is also supported
220 * $promise = Queue::any(10, $jobs, array($browser, 'get'));
221 * ```
222 *
223 * @template TKey
224 * @template TIn
225 * @template TOut
226 * @param int $concurrency concurrency soft limit
227 * @param array<TKey,TIn> $jobs
228 * @param callable(TIn):PromiseInterface<TOut> $handler
229 * @return PromiseInterface<TOut> Returns a Promise which resolves with a single resolution value
230 * or rejects when all of the operations reject.
231 */
232 public static function any($concurrency, array $jobs, $handler)
233 {
234 // explicitly reject with empty jobs (https://github.com/reactphp/promise/pull/34)
235 if (!$jobs) {
236 return Promise\reject(new \UnderflowException('No jobs given'));
237 }
238
239 try {
240 // limit number of concurrent operations
241 $q = new self($concurrency, null, $handler);
242 } catch (\InvalidArgumentException $e) {
243 // reject if $concurrency or $handler is invalid
244 return Promise\reject($e);
245 }
246
247 // try invoking all operations and automatically queue excessive ones
248 $promises = array_map($q, $jobs);
249
250 return new Promise\Promise(function ($resolve, $reject) use ($promises) {
251 Promise\any($promises)->then(function ($result) use ($promises, $resolve) {
252 // cancel all pending promises if a single result is ready
253 foreach (array_reverse($promises) as $promise) {
254 if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
255 $promise->cancel();
256 }
257 }
258
259 // resolve with original resolution value
260 $resolve($result);
261 }, $reject);
262 }, function () use ($promises) {
263 // cancel all pending promises on cancellation
264 foreach (array_reverse($promises) as $promise) {
265 if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
266 $promise->cancel();
267 }
268 }
269 });
270 }
271
272 /**
273 * Instantiates a new queue object.
274 *
275 * You can create any number of queues, for example when you want to apply
276 * different limits to different kind of operations.
277 *
278 * The `$concurrency` parameter sets a new soft limit for the maximum number
279 * of jobs to handle concurrently. Finding a good concurrency limit depends
280 * on your particular use case. It's common to limit concurrency to a rather
281 * small value, as doing more than a dozen of things at once may easily
282 * overwhelm the receiving side.
283 *
284 * The `$limit` parameter sets a new hard limit on how many jobs may be
285 * outstanding (kept in memory) at once. Depending on your particular use
286 * case, it's usually safe to keep a few hundreds or thousands of jobs in
287 * memory. If you do not want to apply an upper limit, you can pass a `null`
288 * value which is semantically more meaningful than passing a big number.
289 *
290 * ```php
291 * // handle up to 10 jobs concurrently, but keep no more than 1000 in memory
292 * $q = new Queue(10, 1000, $handler);
293 * ```
294 *
295 * ```php
296 * // handle up to 10 jobs concurrently, do not limit queue size
297 * $q = new Queue(10, null, $handler);
298 * ```
299 *
300 * ```php
301 * // handle up to 10 jobs concurrently, reject all further jobs
302 * $q = new Queue(10, 10, $handler);
303 * ```
304 *
305 * The `$handler` parameter must be a valid callable that accepts your job
306 * parameters, invokes the appropriate operation and returns a Promise as a
307 * placeholder for its future result.
308 *
309 * ```php
310 * // using a Closure as handler is usually recommended
311 * $q = new Queue(10, null, function ($url) use ($browser) {
312 * return $browser->get($url);
313 * });
314 * ```
315 *
316 * ```php
317 * // PHP's array callable as handler is also supported
318 * $q = new Queue(10, null, array($browser, 'get'));
319 * ```
320 *
321 * @template A1 (any number of function arguments, see https://github.com/phpstan/phpstan/issues/8214)
322 * @template A2
323 * @template A3
324 * @template A4
325 * @template A5
326 * @param int $concurrency concurrency soft limit
327 * @param int|null $limit queue hard limit or NULL=unlimited
328 * @param callable(A1,A2,A3,A4,A5):PromiseInterface<T> $handler
329 * @throws \InvalidArgumentException
330 */
331 public function __construct($concurrency, $limit, $handler)
332 {
333 if ($concurrency < 1 || ($limit !== null && ($limit < 1 || $concurrency > $limit))) {
334 throw new \InvalidArgumentException('Invalid limit given');
335 }
336 if (!is_callable($handler)) {
337 throw new \InvalidArgumentException('Invalid handler given');
338 }
339
340 $this->concurrency = $concurrency;
341 $this->limit = $limit;
342 $this->handler = $handler;
343 }
344
345 /**
346 * The Queue instance is invokable, so that invoking `$q(...$args)` will
347 * actually be forwarded as `$handler(...$args)` as given in the
348 * `$handler` argument when concurrency is still below limits.
349 *
350 * Each operation may take some time to complete, but due to its async nature you
351 * can actually start any number of (queued) operations. Once the concurrency limit
352 * is reached, this invocation will simply be queued and this will return a pending
353 * promise which will start the actual operation once another operation is
354 * completed. This means that this is handled entirely transparently and you do not
355 * need to worry about this concurrency limit yourself.
356 *
357 * @return PromiseInterface<T>
358 */
359 public function __invoke()
360 {
361 // happy path: simply invoke handler if we're below concurrency limit
362 if ($this->pending < $this->concurrency) {
363 ++$this->pending;
364
365 // invoke handler and await its resolution before invoking next queued job
366 return $this->await(
367 call_user_func_array($this->handler, func_get_args())
368 );
369 }
370
371 // we're currently above concurrency limit, make sure we do not exceed maximum queue limit
372 if ($this->limit !== null && $this->count() >= $this->limit) {
373 return Promise\reject(new \OverflowException('Maximum queue limit of ' . $this->limit . ' exceeded'));
374 }
375
376 // if we reach this point, then this job will need to be queued
377 // get next queue position
378 $queue =& $this->queue;
379 $queue[] = null;
380 end($queue);
381 $id = key($queue);
382 assert(is_int($id));
383
384 /** @var ?PromiseInterface<T> $pending */
385 $pending = null;
386
387 $deferred = new Deferred(function ($_, $reject) use (&$queue, $id, &$pending) {
388 // forward cancellation to pending operation if it is currently executing
389 if ($pending instanceof PromiseInterface && \method_exists($pending, 'cancel')) {
390 $pending->cancel();
391 }
392 $pending = null;
393
394 if (isset($queue[$id])) {
395 // queued promise cancelled before its handler is invoked
396 // remove from queue and reject explicitly
397 unset($queue[$id]);
398 $reject(new \RuntimeException('Cancelled queued job before processing started'));
399 }
400 });
401
402 // queue job to process if number of pending jobs is below concurrency limit again
403 $handler = $this->handler; // PHP 5.4+
404 $args = func_get_args();
405 $that = $this; // PHP 5.4+
406 $queue[$id] = function () use ($handler, $args, $deferred, &$pending, $that) {
407 $pending = \call_user_func_array($handler, $args);
408
409 $that->await($pending)->then(
410 function ($result) use ($deferred, &$pending) {
411 $pending = null;
412 $deferred->resolve($result);
413 },
414 function ($e) use ($deferred, &$pending) {
415 $pending = null;
416 $deferred->reject($e);
417 }
418 );
419 };
420
421 return $deferred->promise();
422 }
423
424 #[\ReturnTypeWillChange]
425 public function count()
426 {
427 return $this->pending + count($this->queue);
428 }
429
430 /**
431 * @internal
432 * @param PromiseInterface<T> $promise
433 */
434 public function await(PromiseInterface $promise)
435 {
436 $that = $this; // PHP 5.4+
437
438 return $promise->then(function ($result) use ($that) {
439 $that->processQueue();
440
441 return $result;
442 }, function ($error) use ($that) {
443 $that->processQueue();
444
445 return Promise\reject($error);
446 });
447 }
448
449 /**
450 * @internal
451 */
452 public function processQueue()
453 {
454 // skip if we're still above concurrency limit or there's no queued job waiting
455 if (--$this->pending >= $this->concurrency || !$this->queue) {
456 return;
457 }
458
459 $next = reset($this->queue);
460 assert($next instanceof \Closure);
461 unset($this->queue[key($this->queue)]);
462
463 // once number of pending jobs is below concurrency limit again:
464 // await this situation, invoke handler and await its resolution before invoking next queued job
465 ++$this->pending;
466
467 // invoke handler and await its resolution before invoking next queued job
468 $next();
469 }
470 }