reactphp / promise-timer

A trivial implementation of timeouts for Promises, built on top of ReactPHP.

Event-driven, non-blocking I/O with PHP.

ReactPHP is a low-level library for event-driven programming in PHP. At its core is an event loop, on top of which it provides low-level utilities, such as: Streams abstraction, async DNS resolver, network client/server, HTTP client/server and interaction with processes. Third-party libraries can use these components to create async network clients/servers and more.

<?php

// $ composer require react/http react/socket # install example using Composer
// $ php example.php # run example on command line, requires no additional web server

require __DIR__ . '/vendor/autoload.php';

$server = new React\Http\HttpServer(function (Psr\Http\Message\ServerRequestInterface $request) {
    return React\Http\Message\Response::plaintext(
        "Hello World!\n"
    );
});

$socket = new React\Socket\SocketServer('127.0.0.1:8080');
$server->listen($socket);

echo "Server running at http://127.0.0.1:8080" . PHP_EOL;

This simple web server written in ReactPHP responds with "Hello World!" for every request.

ReactPHP is production ready and battle-tested with millions of installations from all kinds of projects around the world. Its event-driven architecture makes it a perfect fit for efficient network servers and clients handling hundreds or thousands of concurrent connections, long-running applications and many other forms of cooperative multitasking with non-blocking I/O operations. What makes ReactPHP special is its vivid ecosystem with hundreds of third-party libraries allowing you to integrate with many existing systems, such as common network services, database systems and other third-party APIs.

• Production ready and battle-tested.
• Rock-solid with stable long-term support (LTS) releases.
• Requires no extensions and runs on any platform - no excuses!
• Takes advantage of optional extensions to get better performance when available.
• Highly recommends latest version of PHP 7+ for best performance and support.
• Supports legacy PHP 5.3+ and HHVM for maximum compatibility.
• Well designed and reusable components.
• Decoupled parts so they can be replaced by alternate implementations.
• Carefully tested (unit & functional).
• Promotes standard PSRs where possible for maximum interoperability.
• Aims to be technology neutral, so you can use your preferred application stack.
• Small core team of professionals supported by large network of outside contributors.

ReactPHP is non-blocking by default. Use workers for blocking I/O. The event loop is based on the reactor pattern (hence the name) and strongly inspired by libraries such as EventMachine (Ruby), Twisted (Python) and Node.js (V8).

This repository you're currently looking at is mostly used as a meta repository to discuss and plan all things @ReactPHP. See the individual components linked below for more details about each component, its documentation and source code.

Core Components

• EventLoop ReactPHP's core reactor event-loop. Read the documentation

• Stream Event-driven readable and writable streams for non-blocking I/O in ReactPHP. Read the documentation

• Promise Promises/A implementation for PHP. Read the documentation

• Async Async utilities and fibers for ReactPHP. Read the documentation

Network Components

• Socket Async, streaming plaintext TCP/IP and secure TLS socket server and client connections for ReactPHP. Read the documentation

• Datagram Event-driven UDP client and server sockets for ReactPHP. Read the documentation

• HTTP Event-driven, streaming HTTP client and server implementation for ReactPHP. Read the documentation

• DNS Async DNS resolver for ReactPHP. Read the documentation

Utility Components

• Cache Async caching for ReactPHP. Read the documentation

• ChildProcess Library for executing child processes. Read the documentation

• PromiseTimer Trivial timeout implementation for ReactPHP's Promise lib. Read the documentation

• PromiseStream The missing link between Promise-land and Stream-land, built on top of ReactPHP. Read the documentation

Built with ReactPHP

• Thruway PHP Client and Router Library for Autobahn and WAMP (Web Application Messaging Protocol) for Real-Time Application Messaging voryx/Thruway

• PPM - PHP Process Manager PPM is a process manager, supercharger and load balancer for modern PHP applications. php-pm/php-pm

• php-ar-drone 🚁 Port of node-ar-drone which allows user to control a Parrot AR Drone over PHP jolicode/php-ar-drone

• Ratchet Asynchronous WebSocket server ratchetphp/Ratchet

• Predis\Async Asynchronous PHP client library for Redis built on top of ReactPHP nrk/predis-async

• clue/redis-server A Redis server implementation in pure PHP clue/redis-server

And many more on our wiki page »

Articles

• Sergey Zhuk A series of articles covering ReactPHP: from the basics to the real application examples. sergeyzhuk.me

• Cees-Jan Kiewiet Blog series about several ReactPHP components and how they work. blog.wyrihaximus.net

• Loïc Faugeron Super Speed Symfony - ReactPHP. gnugat.github.io

• Marc J. Schmidt Bring High Performance Into Your PHP App (with ReactPHP). marcjschmidt.de

• Marc Morera When ReactPHP meet Symfony medium.com/@apisearch

Talks

• Christian Lück Pushing the limits with ReactPHP

• Jeremy Mikola Async PHP With React

• Igor Wiedler Event-driven PHP

Getting started

ReactPHP consists of a set of individual components. This means that instead of installing something like a "ReactPHP framework", you actually pick only the components that you need.

This project follows SemVer for all its stable components. The recommended way to install these components is through Composer. New to Composer?

For example, this may look something like this:

# recommended install: pick required components
composer require react/event-loop react/http

As an alternative, we also provide a meta package that will install all stable components at once. Installing this is only recommended for quick prototyping, as the list of stable components may change over time. This meta package can be installed like this:

# quick protoyping only: install all stable components
composer require react/react:^1.4

For more details, check out ReactPHP's homepage for quickstart examples and usage details.

See also the combined changelog for all ReactPHP components for details about version upgrades.

Support

Do you have a question and need help with ReactPHP? Don't worry, we're here to help!

As a first step, check the elaborate documentation that comes with each component (see links to individual documentation for each component above). If you find your question is not answered within the documentation, there's a fair chance that it may be relevant to more people. Please do not hesitate to file your question as an issue in the relevant component so others can also participate.

You can also check out our official Gitter chat room. Most of the people involved in this project are available in this chat room, so many questions get answered in a few minutes to some hours. We also use this chat room to announce all new releases and ongoing development efforts, so consider staying in this chat room for a little longer.

Also follow @reactphp on Twitter for updates. We use this mostly for noteworthy, bigger updates and to keep the community updated about ongoing development efforts. You can always use the #reactphp hashtag if you have anything to share!

We're a very open project and we prefer public communication whenever possible, so that more people can participate and help getting the best solutions available. At the same time, we realize that some things are better addressed in private. Whether you just want to say thank you, want to report a security issue or want to help sponsor a certain feature development, you can reach out to the core team in private by sending an email to [email protected]. Please keep in mind that we're a small team of volunteers and do our best to support anybody reaching out.

Do you want to support ReactPHP? Awesome! Let's start with letting the the world know why you think ReactPHP is awesome and try to help others getting on board! Send a tweet, write a blog post, give a talk at your local user group or conference or even write a book. There are many ways you can help. You can always reach out to us in private and help others in our support channels. Thank you!

Tests

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

composer install

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

vendor/bin/phpunit

The test suite also contains a number of functional integration tests that rely on a stable internet connection. Due to the vast number of integration tests, these are skipped by default during CI runs. If you also do not want to run these, they can simply be skipped like this:

vendor/bin/phpunit --exclude-group internet

License

MIT, see LICENSE.

promise-timer's Issues

Support collection operations

What is the recommended way to wait for a timeout of multiple promises?

react/promise provides several promise collection primitives, which all have valid use cases.

One might assume the following is the way to go:

$promises = array(
    accessSomeRemoteResource(),
    accessSomeRemoteResource(),
    accessSomeRemoteResource()
);

$promise = \React\Promise\all($promises);

Timer\timeout($promise, 10, $loop)->then(function ($values) {
    // *all* promises resolved
});

How does this cope with cancellation support? (Refs #9 and #3)

Rename to promise-timer

After talking to @jsor about #2 we agree that the packge name should be changed.

The package name should be "promise-timer" instead of "promise-timeout", as only a single function actually deals with timing out promises.

Accordingly, the namespace should be changed from "Promise\Timeout" to "Promise\Timer" (see also #10).

Timeout\await() => Timeout\timeout() => Timer\timeout() (see also #10)
Timeout\resolve() => Timer\resolve()
Timeout\reject() => Timer\reject()

Keep functional API in mind (singularity)

Passing the $loop parameter is often cumbersome…

Refs reactphp/reactphp#330

Use Promise v2 API instead of Deferreds

Depends on reactphp/promise#31

Psalm in combination with v1.8.0

Hi,

Since the recent v1.8.0 release I am having some problems with Psalm.

There is an example listed in the README of this project:

Or if you're using react/promise v2.2.0 or up:

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

However when running Psalm with errorLevel 5 or lower I get:

ERROR: UndefinedInterfaceMethod - Method React\Promise\PromiseInterface::otherwise does not exist (see https://psalm.dev/181)
            ->otherwise(function (\React\Promise\Timer\TimeoutException $error) {

I guess this is caused by the return type hint of PromiseInterface that was added to \React\Promise\Timer\timeout.

This timeout() function is returning a new Promise(), would it be an idea to change the docblock to @return Promise or @return ExtendedPromiseInterface?

Rename await() to timeout()

After talking to @jsor about #2 we agree that the name await() implies a similarity with the await keyword in ES6/HHVM.

The function name "Timeout\await()" combined makes sense, but not in isolation. As a first step, let's rename this to "Timeout\timeout()".

Obviously, this isn't ideal either, so we should also rename the namespace…

Consider supporting foreign promises

Originally suggested by @jsor in #18 (comment).

Likely depends on reactphp/promise#45

Do not cancel promise once timeout fires

Currently, the promise will be cancelled (edit: rejected) once the timeout fires. This is debatable, but IMHO the name "timeout" implies that we either wait for the promise to settle within the timeout or will never care about its (possible) future result.

Arguably, another use case would be "checking" whether a promise settles within a given time frame. I'd like to put this out here to see if anybody happens to have any thoughts and/or actual use cases.

Also refs clue/reactphp-block#4

Performance

I read the source of promise-timer , I see that for each timer we have a addTimer , I am working on a project with huge request , about 10M/s

I want to know If we have 10M timer , Is this impact performance?
Is it better that we have a timer that manager all 10M request , I don't need accuracy , for me 3 or 4 sec for timer is not important

Do you have any better idea?

Provide function that combines `sleep()` and `timeout()`

For an event-driven API with user interactions, I need to provide endpoints that delay the response for a while to wait for potential interactions and take an action once a timeout is reached.

I've implemented something in a possibly hacky way and believe it would be a potential feature for this lib:

namespace React\Promise\Timer;

use Closure;

use function React\Async\async;
use function React\Async\await;

/**
 * @param Closure():bool $stopCondition,
 * @param Closure():void $onTimeout
 */
function waitUntil(
    Closure $stopCondition,
    float $verificationInterval,
    Closure $onTimeout,
    float $timeout,
): void {
    try {
        $wait = async(static function () use ($stopCondition, $verificationInterval): void {
            while (! $stopCondition()) {
                await(sleep($verificationInterval)); // Timer\sleep() btw
            }
        });

        await(timeout($wait(), $timeout)); // Timer\timeout() btw
    } catch (TimeoutException) {
        $onTimeout();
    }
}

You certainly have ideas on how to turn this into a decent feature or just bin it.
I'm happy either way 😂

Adding timeout to settled input Promise should not start timer

See also #6.

Next steps for PromiseTimer with ReactPHP v3

We're currently moving forward with working on ReactPHP v3 and releasing the roadmap tickets for all our components (see reactphp/event-loop#271 and others). We still have some components that we haven't finalized plans for, especially with the next major version approaching. It's important to address how we can make sure these components are aligned with the upcoming ReactPHP v3.

This discussion about the PromiseTimer component is somewhat similar to reactphp/promise-stream#40 and https://github.com/orgs/reactphp/discussions/475. We already started to remove additional dependencies of PromiseTimer where possible (see reactphp/socket#305, reactphp/dns#213, clue/reactphp-redis#154 and others) and after taking a look at Packagist, it seems like PromiseTimer is only used as a dev-dependency for tests in other ReactPHP components.

This raises the same questions as in PromiseStream, should we move the ReactPHP PromiseTimer component to Friends of ReactPHP, or should we simply reuse the logic elsewhere and deprecate the component afterwards together with the EOL of ReactPHP v1.

Happy about input on this, so let's discuss possible options and decide on what makes the most sense 🚀

Create me

Consider moving to React namespace

createSocket () how to use ?

accessSomeRemoteResource inside the createSocket () how to use, can give an example?

Where is the documentation?

:)

Timer seems to be not working..

Hello,

I've been trying to use your package, however, I do seem to be unable to set it up properly.

To start with, here's my setup:

 ~ php -v
PHP 7.1.8 (cli) (built: Aug 25 2017 10:11:33) ( NTS )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2017 Zend Technologies

Composer.lock contents:

...
"name": "react/promise-timer",
"version": "v1.2.0",
...

Here's a code example:

$loop = \React\EventLoop\Factory::create();

$promise = new Promise(function ($resolve, $reject) {
    $seconds = 10;
    sleep($seconds);
    $resolve("Unexpected Behavior.. Should've thrown an exception..");
}, function ($resolve, $reject) {
    $reject(new \Exception());
});

timeout($promise, 5, $loop)->then(function ($value) {
    die(var_dump($value));
})->otherwise(function (Exception $exception) {
    die(var_dump('Expected behavior..'));
});

The output:

string(53) "Unexpected Behavior.. Should've thrown an exception.."

From my understanding, I should've received the "Expected behavior.." string as a result..

Am I doing anything wrong?

Thank you in advance,
Rad

Promise timer wont stop sub-processes

Hi dear @clue ,
I Think I found a bug!
or I am just confused how this promise-timer works!

When I below Code, My Base Promise Canceled But Sub-processes wont stop and continue their works

<?php

use React\Promise\Promise;
use React\Promise\Timer\TimeoutException;
use function React\Promise\Timer\timeout;

require "vendor/autoload.php";

// Setup EventLoop
$loop = React\EventLoop\Loop::get();

timeout(
    new Promise(function () {
        echo "Task Start" . PHP_EOL;
        return \React\Promise\Timer\sleep(10)
            ->then(function () {
                echo "Sleep Complete and Run" . PHP_EOL;
            });
    }, function () {
        echo "Promise Canceled" . PHP_EOL;
    }), 5)
    ->then(function ($result) {
        // on Success
        echo "Task Success Finalized";
        return true;
    }, function (\Exception $error) {
        // on Timeout/failed
        if ($error instanceof TimeoutException) {
            echo "Task Timeout-ed" . PHP_EOL;
        } else {
            echo "Task Exception" . PHP_EOL;
        }

        return false;
    });


$loop->run();

and Code Response:

Task Start
Task Timeout-ed
Promise Canceled
Sleep Complete and Run

Why it act like that and wont stop sub-processes?
whats wrong in my Ideology؟

Fix PHP 5.3 compatibility

Support Promise cancellation

Implementation is relatively straight forward, but non-trivial, considering the number of required test cases.

Look into avoiding to start timers if timeout is small