JYmusic跨平台音乐管理系统v2.0版本

React/Promise ============= A lightweight implementation of [CommonJS Promises/A](http://wiki.commonjs.org/wiki/Promises/A) for PHP. [](http://travis-ci.org/reactphp/promise) [](https://coveralls.io/github/reactphp/promise?branch=master) Table of Contents ----------------- 1. [Introduction](#introduction) 2. [Concepts](#concepts) * [Deferred](#deferred) * [Promise](#promise) 3. [API](#api) * [Deferred](#deferred-1) * [Deferred::promise()](#deferredpromise) * [Deferred::resolve()](#deferredresolve) * [Deferred::reject()](#deferredreject) * [Deferred::notify()](#deferrednotify) * [PromiseInterface](#promiseinterface) * [PromiseInterface::then()](#promiseinterfacethen) * [ExtendedPromiseInterface](#extendedpromiseinterface) * [ExtendedPromiseInterface::done()](#extendedpromiseinterfacedone) * [ExtendedPromiseInterface::otherwise()](#extendedpromiseinterfaceotherwise) * [ExtendedPromiseInterface::always()](#extendedpromiseinterfacealways) * [ExtendedPromiseInterface::progress()](#extendedpromiseinterfaceprogress) * [CancellablePromiseInterface](#cancellablepromiseinterface) * [CancellablePromiseInterface::cancel()](#cancellablepromiseinterfacecancel) * [Promise](#promise-1) * [FulfilledPromise](#fulfilledpromise) * [RejectedPromise](#rejectedpromise) * [LazyPromise](#lazypromise) * [Functions](#functions) * [resolve()](#resolve) * [reject()](#reject) * [all()](#all) * [race()](#race) * [any()](#any) * [some()](#some) * [map()](#map) * [reduce()](#reduce) * [PromisorInterface](#promisorinterface) 4. [Examples](#examples) * [How to use Deferred](#how-to-use-deferred) * [How promise forwarding works](#how-promise-forwarding-works) * [Resolution forwarding](#resolution-forwarding) * [Rejection forwarding](#rejection-forwarding) * [Mixed resolution and rejection forwarding](#mixed-resolution-and-rejection-forwarding) * [Progress event forwarding](#progress-event-forwarding) * [done() vs. then()](#done-vs-then) 5. [Credits](#credits) 6. [License](#license) Introduction ------------ React/Promise is a library implementing [CommonJS Promises/A](http://wiki.commonjs.org/wiki/Promises/A) for PHP. It also provides several other useful promise-related concepts, such as joining multiple promises and mapping and reducing collections of promises. If you've never heard about promises before, [read this first](https://gist.github.com/3889970). Concepts -------- ### Deferred A **Deferred** represents a computation or unit of work that may not have completed yet. Typically (but not always), that computation will be something that executes asynchronously and completes at some point in the future. ### Promise While a deferred represents the computation itself, a **Promise** represents the result of that computation. Thus, each deferred has a promise that acts as a placeholder for its actual result. API --- ### Deferred A deferred represents an operation whose resolution is pending. It has separate promise and resolver parts. ```php $deferred = new React\Promise\Deferred(); $promise = $deferred->promise(); $deferred->resolve(mixed $value = null); $deferred->reject(mixed $reason = null); $deferred->notify(mixed $update = null); ``` The `promise` method returns the promise of the deferred. The `resolve` and `reject` methods control the state of the deferred. The `notify` method is for progress notification. The constructor of the `Deferred` accepts an optional `$canceller` argument. See [Promise](#promise-1) for more information. #### Deferred::promise() ```php $promise = $deferred->promise(); ``` Returns the promise of the deferred, which you can hand out to others while keeping the authority to modify its state to yourself. #### Deferred::resolve() ```php $deferred->resolve(mixed $value = null); ``` Resolves the promise returned by `promise()`. All consumers are notified by having `$onFulfilled` (which they registered via `$promise->then()`) called with `$value`. If `$value` itself is a promise, the promise will transition to the state of this promise once it is resolved. #### Deferred::reject() ```php $deferred->reject(mixed $reason = null); ``` Rejects the promise returned by `promise()`, signalling that the deferred's computation failed. All consumers are notified by having `$onRejected` (which they registered via `$promise->then()`) called with `$reason`. If `$reason` itself is a promise, the promise will be rejected with the outcome of this promise regardless whether it fulfills or rejects. #### Deferred::notify() ```php $deferred->notify(mixed $update = null); ``` Triggers progress notifications, to indicate to consumers that the computation is making progress toward its result. All consumers are notified by having `$onProgress` (which they registered via `$promise->then()`) called with `$update`. ### PromiseInterface The promise interface provides the common interface for all promise implementations. A promise represents an eventual outcome, which is either fulfillment (success) and an associated value, or rejection (failure) and an associated reason. Once in the fulfilled or rejected state, a promise becomes immutable. Neither its state nor its result (or error) can be modified. #### Implementations * [Promise](#promise-1) * [FulfilledPromise](#fulfilledpromise) * [RejectedPromise](#rejectedpromise) * [LazyPromise](#lazypromise) #### PromiseInterface::then() ```php $transformedPromise = $promise->then(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null); ``` Transforms a promise's value by applying a function to the promise's fulfillment or rejection value. Returns a new promise for the transformed result. The `then()` method registers new fulfilled, rejection and progress handlers with a promise (all parameters are optional): * `$onFulfilled` will be invoked once the promise is fulfilled and passed the result as the first argument. * `$onRejected` will be invoked once the promise is rejected and passed the reason as the first argument. * `$onProgress` will be invoked whenever the producer of the promise triggers progress notifications and passed a single argument (whatever it wants) to indicate progress. It returns a new promise that will fulfill with the return value of either `$onFulfilled` or `$onRejected`, whichever is called, or will reject with the thrown exception if either throws. A promise makes the following guarantees about handlers registered in the same call to `then()`: 1. Only one of `$onFulfilled` or `$onRejected` will be called, never both. 2. `$onFulfilled` and `$onRejected` will never be called more than once. 3. `$onProgress` may be called multiple times. #### See also * [resolve()](#resolve) - Creating a resolved promise * [reject()](#reject) - Creating a rejected promise * [ExtendedPromiseInterface::done()](#extendedpromiseinterfacedone) * [done() vs. then()](#done-vs-then) ### ExtendedPromiseInterface The ExtendedPromiseInterface extends the PromiseInterface with useful shortcut and utility methods which are not part of the Promises/A specification. #### Implementations * [Promise](#promise-1) * [FulfilledPromise](#fulfilledpromise) * [RejectedPromise](#rejectedpromise) * [LazyPromise](#lazypromise) #### ExtendedPromiseInterface::done() ```php $promise->done(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null); ``` Consumes the promise's ultimate value if the promise fulfills, or handles the ultimate error. It will cause a fatal error if either `$onFulfilled` or `$onRejected` throw or return a rejected promise. Since the purpose of `done()` is c