1
0
mirror of https://github.com/danog/amp.git synced 2024-12-04 18:38:17 +01:00
amp/lib/CancellationTokenSource.php

149 lines
4.3 KiB
PHP
Raw Normal View History

<?php
namespace Amp;
/**
* A cancellation token source provides a mechanism to cancel operations.
*
* Cancellation of operation works by creating a cancellation token source and passing the corresponding token when
* starting the operation. To cancel the operation, invoke `CancellationTokenSource::cancel()`.
*
* Any operation can decide what to do on a cancellation request, it has "don't care" semantics. An operation SHOULD be
* aborted, but MAY continue. Example: A DNS client might continue to receive and cache the response, as the query has
* been sent anyway. An HTTP client would usually close a connection, but might not do so in case a response is close to
* be fully received to reuse the connection.
*
* **Example**
*
* ```php
2017-05-16 21:46:52 +02:00
* $tokenSource = new CancellationTokenSource;
* $token = $tokenSource->getToken();
*
2020-08-23 16:18:28 +02:00
* $response = yield $httpClient->request("https://example.com/pipeline", $token);
* $responseBody = $response->getBody();
*
* while (($chunk = yield $response->read()) !== null) {
* // consume $chunk
*
* if ($noLongerInterested) {
* $cancellationTokenSource->cancel();
* break;
* }
* }
* ```
*
* @see CancellationToken
* @see CancelledException
*/
2018-06-18 20:00:01 +02:00
final class CancellationTokenSource
{
private CancellationToken $token;
/** @var callable|null */
private $onCancel;
2018-06-18 20:00:01 +02:00
public function __construct()
{
2020-10-02 20:55:46 +02:00
$onCancel = &$this->onCancel;
$this->token = new class($onCancel) implements CancellationToken {
private string $nextId = "a";
/** @var callable[] */
private array $callbacks = [];
/** @var \Throwable|null */
private ?\Throwable $exception = null;
/**
2020-10-02 20:55:46 +02:00
* @param callable|null $onCancel
* @param-out callable $onCancel
*/
2020-10-02 20:55:46 +02:00
public function __construct(?callable &$onCancel)
2018-06-18 20:00:01 +02:00
{
2020-10-02 20:55:46 +02:00
$onCancel = function (\Throwable $exception): void {
$this->exception = $exception;
$callbacks = $this->callbacks;
$this->callbacks = [];
foreach ($callbacks as $callback) {
$this->invokeCallback($callback);
}
};
}
/**
* @param callable $callback
*
* @return void
*/
private function invokeCallback(callable $callback): void
2018-06-18 20:00:01 +02:00
{
// No type declaration to prevent exception outside the try!
try {
/** @var mixed $result */
$result = $callback($this->exception);
if ($result instanceof Promise) {
Promise\rethrow($result);
}
} catch (\Throwable $exception) {
2020-10-02 20:55:46 +02:00
Loop::defer(static function () use ($exception): void {
throw $exception;
});
}
}
2018-06-18 20:00:01 +02:00
public function subscribe(callable $callback): string
{
$id = $this->nextId++;
if ($this->exception) {
$this->invokeCallback($callback);
} else {
$this->callbacks[$id] = $callback;
}
return $id;
}
public function unsubscribe(string $id): void
2018-06-18 20:00:01 +02:00
{
unset($this->callbacks[$id]);
}
2018-06-18 20:00:01 +02:00
public function isRequested(): bool
{
return isset($this->exception);
}
public function throwIfRequested(): void
2018-06-18 20:00:01 +02:00
{
if (isset($this->exception)) {
throw $this->exception;
}
}
};
}
2018-06-18 20:00:01 +02:00
public function getToken(): CancellationToken
{
return $this->token;
}
2017-06-13 19:41:47 +02:00
/**
* @param \Throwable|null $previous Exception to be used as the previous exception to CancelledException.
*/
2020-10-02 20:55:46 +02:00
public function cancel(\Throwable $previous = null): void
2018-06-18 20:00:01 +02:00
{
if ($this->onCancel === null) {
return;
}
$onCancel = $this->onCancel;
$this->onCancel = null;
2020-10-02 20:55:46 +02:00
Loop::defer(static fn () => $onCancel(new CancelledException($previous)));
}
}