Repository files navigation

A trivial implementation of timeouts forPromises, built on top ofReactPHP.

Table of contents

• Usage
  • timeout()
  • sleep()
  • resolve()
  • reject()
  • TimeoutException
    • getTimeout()
• Install
• Tests
• License

This lightweight library consists only of a few simple functions.All functions reside under theReact\Promise\Timer namespace.

The below examples refer to all functions with their fully-qualified names like this:

React\Promise\Timer\timeout(…);

As of PHP 5.6+ you can also import each required function into your code like this:

usefunctionReact\Promise\Timer\timeout;timeout(…);

Alternatively, you can also use an import statement similar to this:

useReact\Promise\Timer;Timer\timeout(…);

Thetimeout(PromiseInterface<T> $promise, float $time, ?LoopInterface $loop = null): PromiseInterface<T> function can be used tocancel operations that taketoo long.

You need to pass in an input$promise that represents a pending operationand timeout parameters. It returns a new promise with the followingresolution behavior:

• If the input$promise resolves before$time seconds, resolve theresulting promise with its fulfillment value.

• If the input$promise rejects before$time seconds, reject theresulting promise with its rejection value.

• If the input$promise does not settle before$time seconds,cancelthe operation and reject the resulting promise with aTimeoutException.

Internally, the given$time value will be used to start a timer that willcancel the pending operation once it triggers. This implies that if youpass a really small (or negative) value, it will still start a timer and willthus trigger at the earliest possible time in the future.

If the input$promise is already settled, then the resulting promise willresolve or reject immediately without starting a timer at all.

This function takes an optionalLoopInterface|null $loop parameter that can be used topass the event loop instance to use. You can use anull value here in order touse thedefault loop. This valueSHOULD NOT be given unless you're sure you want to explicitly use a given eventloop instance.

A common use case for handling only resolved values looks like this:

$promise =accessSomeRemoteResource();React\Promise\Timer\timeout($promise,10.0)->then(function ($value) {// the operation finished within 10.0 seconds});

A more complete example could look like this:

$promise =accessSomeRemoteResource();React\Promise\Timer\timeout($promise,10.0)->then(function ($value) {// the operation finished within 10.0 seconds    },function ($error) {if ($errorinstanceofReact\Promise\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 usingreact/promise v3:

React\Promise\Timer\timeout($promise,10.0)->then(function ($value) {// the operation finished within 10.0 seconds})->catch(function (React\Promise\Timer\TimeoutException$error) {// the operation has failed due to a timeout})->catch(function (Throwable$error) {// the input operation has failed due to some other error});

As discussed above, thetimeout() function will take care ofthe underlying operation if it takestoo long. In this case, you can besure the resulting promise will always be rejected with aTimeoutException. On top of this, the function willtry tocancel the underlying operation. Responsibility for thiscancellation logic is left up to the underlying operation.

• A common use case involves cleaning up any resources like open networksockets or file handles or terminating external processes or timers.

• If the given input$promise does not support cancellation, then this is aNO-OP. This means that while the resulting promise will still be rejected,the underlying input$promise may still be pending and can hence continueconsuming resources

On top of this, the returned promise is implemented in such a way that it canbe cancelled when it is still pending. Cancelling a pending promise willcancel the underlying operation. As discussed above, responsibility for thiscancellation logic is left up to the underlying operation.

$promise =accessSomeRemoteResource();$timeout =React\Promise\Timer\timeout($promise,10.0);$timeout->cancel();

For more details on the promise cancellation, please refer to thePromise documentation.

If you want to wait for multiple promises to resolve, you can use the normalpromise primitives like this:

$promises =array(accessSomeRemoteResource(),accessSomeRemoteResource(),accessSomeRemoteResource());$promise =React\Promise\all($promises);React\Promise\Timer\timeout($promise,10)->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 thePromise documentation.

Thesleep(float $time, ?LoopInterface $loop = null): PromiseInterface<void> function can be used tocreate a new promise that resolves in$time seconds.

React\Promise\Timer\sleep(1.5)->then(function () {echo'Thanks for waiting!' .PHP_EOL;});

Internally, the given$time value will be used to start a timer that willresolve the promise once it triggers. This implies that if you pass a reallysmall (or negative) value, it will still start a timer and will thus triggerat the earliest possible time in the future.

This function takes an optionalLoopInterface|null $loop parameter that can be used topass the event loop instance to use. You can use anull value here in order touse thedefault loop. This valueSHOULD NOT be given unless you're sure you want to explicitly use a given eventloop instance.

The returned promise is implemented in such a way that it can be cancelledwhen it is still pending. Cancelling a pending promise will reject its valuewith aRuntimeException and clean up any pending timers.

$timer =React\Promise\Timer\sleep(2.0);$timer->cancel();

Deprecated since v1.8.0, seesleep() instead.

Theresolve(float $time, ?LoopInterface $loop = null): PromiseInterface<float> function can be used tocreate a new promise that resolves in$time seconds with the$time as the fulfillment value.

React\Promise\Timer\resolve(1.5)->then(function ($time) {echo'Thanks for waiting' .$time .' seconds' .PHP_EOL;});

Internally, the given$time value will be used to start a timer that willresolve the promise once it triggers. This implies that if you pass a reallysmall (or negative) value, it will still start a timer and will thus triggerat the earliest possible time in the future.

This function takes an optionalLoopInterface|null $loop parameter that can be used topass the event loop instance to use. You can use anull value here in order touse thedefault loop. This valueSHOULD NOT be given unless you're sure you want to explicitly use a given eventloop instance.

The returned promise is implemented in such a way that it can be cancelledwhen it is still pending. Cancelling a pending promise will reject its valuewith aRuntimeException and clean up any pending timers.

$timer =React\Promise\Timer\resolve(2.0);$timer->cancel();

Deprecated since v1.8.0, seesleep() instead.

Thereject(float $time, ?LoopInterface $loop = null): PromiseInterface<never> function can be used tocreate a new promise which rejects in$time seconds with aTimeoutException.

React\Promise\Timer\reject(2.0)->then(null,function (React\Promise\Timer\TimeoutException$e) {echo'Rejected after' .$e->getTimeout() .' seconds' .PHP_EOL;});

Internally, the given$time value will be used to start a timer that willreject the promise once it triggers. This implies that if you pass a reallysmall (or negative) value, it will still start a timer and will thus triggerat the earliest possible time in the future.

This function takes an optionalLoopInterface|null $loop parameter that can be used topass the event loop instance to use. You can use anull value here in order touse thedefault loop. This valueSHOULD NOT be given unless you're sure you want to explicitly use a given eventloop instance.

The returned promise is implemented in such a way that it can be cancelledwhen it is still pending. Cancelling a pending promise will reject its valuewith aRuntimeException and clean up any pending timers.

$timer =React\Promise\Timer\reject(2.0);$timer->cancel();

TheTimeoutException extends PHP's built-inRuntimeException.

ThegetTimeout(): float method can be used toget the timeout value in seconds.

The recommended way to install this library isthrough Composer.New to Composer?

This project followsSemVer.This will install the latest supported version:

composer require react/promise-timer:^1.11

See also theCHANGELOG for details about version upgrades.

This project aims to run on any platform and thus does not require any PHPextensions and supports running on legacy PHP 5.3 through current PHP 8+ andHHVM.It'shighly recommended to use the latest supported PHP version for this project.

To run the test suite, you first need to clone this repo and then install alldependenciesthrough Composer:

composer install

To run the test suite, go to the project root and run:

vendor/bin/phpunit

MIT, seeLICENSE file.