diff options
Diffstat (limited to 'assets/php/vendor/react/promise-timer/README.md')
| -rwxr-xr-x | assets/php/vendor/react/promise-timer/README.md | 372 |
1 files changed, 0 insertions, 372 deletions
diff --git a/assets/php/vendor/react/promise-timer/README.md b/assets/php/vendor/react/promise-timer/README.md deleted file mode 100755 index 2ea94fa..0000000 --- a/assets/php/vendor/react/promise-timer/README.md +++ /dev/null @@ -1,372 +0,0 @@ -# PromiseTimer - -[](https://travis-ci.org/reactphp/promise-timer) - -A trivial implementation of timeouts for `Promise`s, built on top of [ReactPHP](https://reactphp.org/). - -**Table of contents** - -* [Usage](#usage) - * [timeout()](#timeout) - * [Timeout cancellation](#timeout-cancellation) - * [Cancellation handler](#cancellation-handler) - * [Input cancellation](#input-cancellation) - * [Output cancellation](#output-cancellation) - * [Collections](#collections) - * [resolve()](#resolve) - * [Resolve cancellation](#resolve-cancellation) - * [reject()](#reject) - * [Reject cancellation](#reject-cancellation) - * [TimeoutException](#timeoutexception) -* [Install](#install) -* [Tests](#tests) -* [License](#license) - -## Usage - -This lightweight library consists only of a few simple functions. -All functions reside under the `React\Promise\Timer` namespace. - -The below examples assume you use an import statement similar to this: - -```php -use React\Promise\Timer; - -Timer\timeout(…); -``` - -Alternatively, you can also refer to them with their fully-qualified name: - -```php -\React\Promise\Timer\timeout(…); -``` - -### timeout() - -The `timeout(PromiseInterface $promise, $time, LoopInterface $loop)` function -can be used to *cancel* operations that take *too long*. -You need to pass in an input `$promise` that represents a pending operation and timeout parameters. -It returns a new `Promise` with the following resolution behavior: - -* If the input `$promise` resolves before `$time` seconds, resolve the resulting promise with its fulfillment value. -* If the input `$promise` rejects before `$time` seconds, reject the resulting promise with its rejection value. -* If the input `$promise` does not settle before `$time` seconds, *cancel* the operation and reject the resulting promise with a [`TimeoutException`](#timeoutexception). - -Internally, the given `$time` value will be used to start a timer that will -*cancel* the pending operation once it triggers. -This implies that if you pass a really small (or negative) value, it will still -start a timer and will thus trigger at the earliest possible time in the future. - -If the input `$promise` is already settled, then the resulting promise will -resolve or reject immediately without starting a timer at all. - -A common use case for handling only resolved values looks like this: - -```php -$promise = accessSomeRemoteResource(); -Timer\timeout($promise, 10.0, $loop)->then(function ($value) { - // the operation finished within 10.0 seconds -}); -``` - -A more complete example could look like this: - -```php -$promise = accessSomeRemoteResource(); -Timer\timeout($promise, 10.0, $loop)->then( - function ($value) { - // the operation finished within 10.0 seconds - }, - function ($error) { - if ($error instanceof Timer\TimeoutException) { - // the operation has failed due to a timeout - } else { - // the input operation has failed due to some other error - } - } -); -``` - -Or if you're using [react/promise v2.2.0](https://github.com/reactphp/promise) or up: - -```php -Timer\timeout($promise, 10.0, $loop) - ->then(function ($value) { - // the operation finished within 10.0 seconds - }) - ->otherwise(function (Timer\TimeoutException $error) { - // the operation has failed due to a timeout - }) - ->otherwise(function ($error) { - // the input operation has failed due to some other error - }) -; -``` - -#### Timeout cancellation - -As discussed above, the [`timeout()`](#timeout) function will *cancel* the -underlying operation if it takes *too long*. -This means that you can be sure the resulting promise will then be rejected -with a [`TimeoutException`](#timeoutexception). - -However, what happens to the underlying input `$promise` is a bit more tricky: -Once the timer fires, we will try to call -[`$promise->cancel()`](https://github.com/reactphp/promise#cancellablepromiseinterfacecancel) -on the input `$promise` which in turn invokes its [cancellation handler](#cancellation-handler). - -This means that it's actually up the input `$promise` to handle -[cancellation support](https://github.com/reactphp/promise#cancellablepromiseinterface). - -* A common use case involves cleaning up any resources like open network sockets or - file handles or terminating external processes or timers. - -* If the given input `$promise` does not support cancellation, then this is a NO-OP. - This means that while the resulting promise will still be rejected, the underlying - input `$promise` may still be pending and can hence continue consuming resources. - -See the following chapter for more details on the cancellation handler. - -#### Cancellation handler - -For example, an implementation for the above operation could look like this: - -```php -function accessSomeRemoteResource() -{ - return new Promise( - function ($resolve, $reject) use (&$socket) { - // this will be called once the promise is created - // a common use case involves opening any resources and eventually resolving - $socket = createSocket(); - $socket->on('data', function ($data) use ($resolve) { - $resolve($data); - }); - }, - function ($resolve, $reject) use (&$socket) { - // this will be called once calling `cancel()` on this promise - // a common use case involves cleaning any resources and then rejecting - $socket->close(); - $reject(new \RuntimeException('Operation cancelled')); - } - ); -} -``` - -In this example, calling `$promise->cancel()` will invoke the registered cancellation -handler which then closes the network socket and rejects the `Promise` instance. - -If no cancellation handler is passed to the `Promise` constructor, then invoking -its `cancel()` method it is effectively a NO-OP. -This means that it may still be pending and can hence continue consuming resources. - -For more details on the promise cancellation, please refer to the -[Promise documentation](https://github.com/reactphp/promise#cancellablepromiseinterface). - -#### Input cancellation - -Irrespective of the timout handling, you can also explicitly `cancel()` the -input `$promise` at any time. -This means that the `timeout()` handling does not affect cancellation of the -input `$promise`, as demonstrated in the following example: - -```php -$promise = accessSomeRemoteResource(); -$timeout = Timer\timeout($promise, 10.0, $loop); - -$promise->cancel(); -``` - -The registered [cancellation handler](#cancellation-handler) is responsible for -handling the `cancel()` call: - -* A described above, a common use involves resource cleanup and will then *reject* - the `Promise`. - If the input `$promise` is being rejected, then the timeout will be aborted - and the resulting promise will also be rejected. -* If the input `$promise` is still pending, then the timout will continue - running until the timer expires. - The same happens if the input `$promise` does not register a - [cancellation handler](#cancellation-handler). - -#### Output cancellation - -Similarily, you can also explicitly `cancel()` the resulting promise like this: - -```php -$promise = accessSomeRemoteResource(); -$timeout = Timer\timeout($promise, 10.0, $loop); - -$timeout->cancel(); -``` - -Note how this looks very similar to the above [input cancellation](#input-cancellation) -example. Accordingly, it also behaves very similar. - -Calling `cancel()` on the resulting promise will merely try -to `cancel()` the input `$promise`. -This means that we do not take over responsibility of the outcome and it's -entirely up to the input `$promise` to handle cancellation support. - -The registered [cancellation handler](#cancellation-handler) is responsible for -handling the `cancel()` call: - -* As described above, a common use involves resource cleanup and will then *reject* - the `Promise`. - If the input `$promise` is being rejected, then the timeout will be aborted - and the resulting promise will also be rejected. -* If the input `$promise` is still pending, then the timout will continue - running until the timer expires. - The same happens if the input `$promise` does not register a - [cancellation handler](#cancellation-handler). - -To re-iterate, note that calling `cancel()` on the resulting promise will merely -try to cancel the input `$promise` only. -It is then up to the cancellation handler of the input promise to settle the promise. -If the input promise is still pending when the timeout occurs, then the normal -[timeout cancellation](#timeout-cancellation) handling will trigger, effectively rejecting -the output promise with a [`TimeoutException`](#timeoutexception). - -This is done for consistency with the [timeout cancellation](#timeout-cancellation) -handling and also because it is assumed this is often used like this: - -```php -$timeout = Timer\timeout(accessSomeRemoteResource(), 10.0, $loop); - -$timeout->cancel(); -``` - -As described above, this example works as expected and cleans up any resources -allocated for the input `$promise`. - -Note that if the given input `$promise` does not support cancellation, then this -is a NO-OP. -This means that while the resulting promise will still be rejected after the -timeout, the underlying input `$promise` may still be pending and can hence -continue consuming resources. - -#### Collections - -If you want to wait for multiple promises to resolve, you can use the normal promise primitives like this: - -```php -$promises = array( - accessSomeRemoteResource(), - accessSomeRemoteResource(), - accessSomeRemoteResource() -); - -$promise = \React\Promise\all($promises); - -Timer\timeout($promise, 10, $loop)->then(function ($values) { - // *all* promises resolved -}); -``` - -The applies to all promise collection primitives alike, i.e. `all()`, `race()`, `any()`, `some()` etc. - -For more details on the promise primitives, please refer to the -[Promise documentation](https://github.com/reactphp/promise#functions). - -### resolve() - -The `resolve($time, LoopInterface $loop)` function can be used to create a new Promise that -resolves in `$time` seconds with the `$time` as the fulfillment value. - -```php -Timer\resolve(1.5, $loop)->then(function ($time) { - echo 'Thanks for waiting ' . $time . ' seconds' . PHP_EOL; -}); -``` - -Internally, the given `$time` value will be used to start a timer that will -resolve the promise once it triggers. -This implies that if you pass a really small (or negative) value, it will still -start a timer and will thus trigger at the earliest possible time in the future. - -#### Resolve cancellation - -You can explicitly `cancel()` the resulting timer promise at any time: - -```php -$timer = Timer\resolve(2.0, $loop); - -$timer->cancel(); -``` - -This will abort the timer and *reject* with a `RuntimeException`. - -### reject() - -The `reject($time, LoopInterface $loop)` function can be used to create a new Promise -which rejects in `$time` seconds with a `TimeoutException`. - -```php -Timer\reject(2.0, $loop)->then(null, function (TimeoutException $e) { - echo 'Rejected after ' . $e->getTimeout() . ' seconds ' . PHP_EOL; -}); -``` - -Internally, the given `$time` value will be used to start a timer that will -reject the promise once it triggers. -This implies that if you pass a really small (or negative) value, it will still -start a timer and will thus trigger at the earliest possible time in the future. - -This function complements the [`resolve()`](#resolve) function -and can be used as a basic building block for higher-level promise consumers. - -#### Reject cancellation - -You can explicitly `cancel()` the resulting timer promise at any time: - -```php -$timer = Timer\reject(2.0, $loop); - -$timer->cancel(); -``` - -This will abort the timer and *reject* with a `RuntimeException`. - -### TimeoutException - -The `TimeoutException` extends PHP's built-in `RuntimeException`. - -The `getTimeout()` method can be used to get the timeout value in seconds. - -## Install - -The recommended way to install this library is [through Composer](https://getcomposer.org). -[New to Composer?](https://getcomposer.org/doc/00-intro.md) - -This project follows [SemVer](http://semver.org/). -This will install the latest supported version: - -```bash -$ composer require react/promise-timer:^1.2.1 -``` - -See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades. - -This project aims to run on any platform and thus does not require any PHP -extensions and supports running on legacy PHP 5.3 through current PHP 7+ and -HHVM. -It's *highly recommended to use PHP 7+* for this project. - -## Tests - -To run the test suite, you first need to clone this repo and then install all -dependencies [through Composer](https://getcomposer.org): - -```bash -$ composer install -``` - -To run the test suite, go to the project root and run: - -```bash -$ php vendor/bin/phpunit -``` - -## License - -MIT, see [LICENSE file](LICENSE). |