1
0
mirror of https://github.com/danog/amp.git synced 2024-12-11 00:49:48 +01:00
amp/lib/Promise.php

39 lines
1.5 KiB
PHP
Raw Normal View History

<?php
namespace Amp;
/**
* Representation of the future value of an asynchronous operation.
*
* @template-covariant TValue
* @psalm-yield TValue
*/
interface Promise
2018-06-18 20:00:01 +02:00
{
/**
2021-02-18 16:56:26 +01:00
* Registers a callback to be invoked when the promise is resolved. Note that using this method directly is
* generally not recommended. Use the {@see await()} function to await promise resolution or use one of the
* combinator functions in the Amp\Promise namespace, such as {@see \Amp\Promise\all()}.
*
2018-03-25 17:27:41 +02:00
* If this method is called multiple times, additional handlers will be registered instead of replacing any already
* existing handlers.
*
2021-02-18 16:56:26 +01:00
* Registered callbacks MUST be invoked asynchronously when the promise is resolved using a defer watcher in the
* event-loop.
*
2017-06-06 19:57:03 +02:00
* Exceptions MUST NOT be thrown from this method. Any exceptions thrown from invoked callbacks MUST be
2021-02-18 16:56:26 +01:00
* forwarded to the event-loop error handler by re-throwing from a defer watcher.
2017-06-06 19:57:03 +02:00
*
2018-03-25 17:27:41 +02:00
* Note: You shouldn't implement this interface yourself. Instead, provide a method that returns a promise for the
* operation you're implementing. Objects other than pure placeholders implementing it are a very bad idea.
*
* @param callable $onResolved The first argument shall be `null` on success, while the second shall be `null` on
* failure.
*
2021-02-18 16:56:26 +01:00
* @psalm-param callable(\Throwable|null, mixed):Promise|null $onResolved
2020-03-21 21:15:39 +01:00
*
* @return void
*/
2020-09-24 18:52:22 +02:00
public function onResolve(callable $onResolved): void;
}