| 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 |
} |