annotate vendor/guzzlehttp/promises/src/PromiseInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2 namespace GuzzleHttp\Promise;
Chris@0 3
Chris@0 4 /**
Chris@0 5 * A promise represents the eventual result of an asynchronous operation.
Chris@0 6 *
Chris@0 7 * The primary way of interacting with a promise is through its then method,
Chris@0 8 * which registers callbacks to receive either a promise’s eventual value or
Chris@0 9 * the reason why the promise cannot be fulfilled.
Chris@0 10 *
Chris@0 11 * @link https://promisesaplus.com/
Chris@0 12 */
Chris@0 13 interface PromiseInterface
Chris@0 14 {
Chris@0 15 const PENDING = 'pending';
Chris@0 16 const FULFILLED = 'fulfilled';
Chris@0 17 const REJECTED = 'rejected';
Chris@0 18
Chris@0 19 /**
Chris@0 20 * Appends fulfillment and rejection handlers to the promise, and returns
Chris@0 21 * a new promise resolving to the return value of the called handler.
Chris@0 22 *
Chris@0 23 * @param callable $onFulfilled Invoked when the promise fulfills.
Chris@0 24 * @param callable $onRejected Invoked when the promise is rejected.
Chris@0 25 *
Chris@0 26 * @return PromiseInterface
Chris@0 27 */
Chris@0 28 public function then(
Chris@0 29 callable $onFulfilled = null,
Chris@0 30 callable $onRejected = null
Chris@0 31 );
Chris@0 32
Chris@0 33 /**
Chris@0 34 * Appends a rejection handler callback to the promise, and returns a new
Chris@0 35 * promise resolving to the return value of the callback if it is called,
Chris@0 36 * or to its original fulfillment value if the promise is instead
Chris@0 37 * fulfilled.
Chris@0 38 *
Chris@0 39 * @param callable $onRejected Invoked when the promise is rejected.
Chris@0 40 *
Chris@0 41 * @return PromiseInterface
Chris@0 42 */
Chris@0 43 public function otherwise(callable $onRejected);
Chris@0 44
Chris@0 45 /**
Chris@0 46 * Get the state of the promise ("pending", "rejected", or "fulfilled").
Chris@0 47 *
Chris@0 48 * The three states can be checked against the constants defined on
Chris@0 49 * PromiseInterface: PENDING, FULFILLED, and REJECTED.
Chris@0 50 *
Chris@0 51 * @return string
Chris@0 52 */
Chris@0 53 public function getState();
Chris@0 54
Chris@0 55 /**
Chris@0 56 * Resolve the promise with the given value.
Chris@0 57 *
Chris@0 58 * @param mixed $value
Chris@0 59 * @throws \RuntimeException if the promise is already resolved.
Chris@0 60 */
Chris@0 61 public function resolve($value);
Chris@0 62
Chris@0 63 /**
Chris@0 64 * Reject the promise with the given reason.
Chris@0 65 *
Chris@0 66 * @param mixed $reason
Chris@0 67 * @throws \RuntimeException if the promise is already resolved.
Chris@0 68 */
Chris@0 69 public function reject($reason);
Chris@0 70
Chris@0 71 /**
Chris@0 72 * Cancels the promise if possible.
Chris@0 73 *
Chris@0 74 * @link https://github.com/promises-aplus/cancellation-spec/issues/7
Chris@0 75 */
Chris@0 76 public function cancel();
Chris@0 77
Chris@0 78 /**
Chris@0 79 * Waits until the promise completes if possible.
Chris@0 80 *
Chris@0 81 * Pass $unwrap as true to unwrap the result of the promise, either
Chris@0 82 * returning the resolved value or throwing the rejected exception.
Chris@0 83 *
Chris@0 84 * If the promise cannot be waited on, then the promise will be rejected.
Chris@0 85 *
Chris@0 86 * @param bool $unwrap
Chris@0 87 *
Chris@0 88 * @return mixed
Chris@0 89 * @throws \LogicException if the promise has no wait function or if the
Chris@0 90 * promise does not settle after waiting.
Chris@0 91 */
Chris@0 92 public function wait($unwrap = true);
Chris@0 93 }