Download the PHP package ajayvohra2005/hack-promises without Composer

Hack Promises

This project provides Promises/A+ implementation in Hack.

Overview

Key features

• Promises have synchronous wait and methods.
• Works with any object that implements
• Support for Hack , and Hack Generator.

Requirements

HHVM 4.128 and above.

Installation

• Git clone this repository
• Install composer

• In the root directory of this repository, run the command

  composer install

To use this package,

    composer require ajayvohra2005/hack-promises

Running tests

After installation, run the following command in the root directory of this repository:

    ./vendor/bin/hacktest tests/

License

This project is made available under the MIT License (MIT). Please see LICENSE file in this project for more information.

Tutorial

A promise represents the result of the resolution of an asynchronous operation, and the side-effects associated with the resolution.

Resolving a promise

Resolving a promise means that a promise is either fulfilled with a value or rejected with a reason. Resolving a promises triggers callbacks registered with the promises's then method. These callbacks are triggered only once and in the order in which they were added. When a callback is triggered, it is added to a global task queue. When the global task queue is , the tasks on the queue are removed and executed in the order they were added to the queue.

Global task queue

The global task queue can be as needed, or in an event loop. By default, the global task queue is run implicitly once prior to the program shutdown. The global task queue can be run explictily as shown below:

  HackPromises\TaskQueue::globalTaskQueue()->run();

Callbacks

Callbacks are registered with a promise by calling the then method of the promise, and by providing optional $onFulfilled and $onRejected functions, whereby the functions must be of type .

When you register callbacks with a promise by calling the method, it always returns a new promise. This can be used to create a chain of promises. The next promise in the chain is invoked with the resolved value of the previous promise in the chain. A promise in the chain is fulfilled only when the previous promise has been fulfilled.

Quick example

Below we show a quick start example that illustrates the concepts discussed so far:

Promise rejection

When a promise is rejected, the $onRejected callbacks are invoked with the rejection reason, as shown in the example below:

Rejection forwarding

If an exception is thrown in an $onRejected callback, subsequent $onRejected callbacks are invoked with the thrown exception as the reason.

If an exception is not thrown in a $onRejected callback and the callback does not return a rejected promise, downstream $onFulfilled callbacks are invoked using the value returned from the $onRejected callback, as shown in the example below:

Synchronous wait

You can resolve a promise synchronously by caling the method on a promise.

Calling the method of a promise invokes the wait function provided to the promise, and implicitly runs the global task queue. An example showing the use of the method is shown below:

If an exception is encountered while invoking the wait function of a promise, the promise is rejected with the exception and the exception is thrown. Calling wait method of a promise that has been fulfilled will not trigger the wait function. It will simply return the previously resolved value

Calling wait method on a promise that has been rejected will throw an exception. If the rejection reason is an instance of \Exception the reason is thrown. Otherwise, a HackPromises\RejectionException is thrown and the reason can be obtained by calling the getReason method of the exception.

Unwrapping a promise

When you call the method without an argument, or with the argument , it unwraps the promiose. Unwrapping the promise returns the value of the promise if it was fulfilled, or throws an exception if the promise was rejected. You can force a promise to resolve but not unwrap by passing false to the wait method of the promise, as shown in the example below:

When unwrapping a promise, the resolved value of the promise will be waited upon until the unwrapped value is not a promise. This means that if you resolve promise A with a promise B and unwrap promise A, the value returned by the wait function will be the result of resolving promise B, as shown in the example below;

Synchronous cancel

You can cancel a promise that has not yet been fulfilled synchronously using the cancel() method of a promise.

API classes

Promise

For the base case, you can use class to create a promise.

If you want to resolve the promise asynchronosuly and invoke the registerd callbacks, you can create the without any arguments to the constructor.

If you want be able to synchronously resolve or cancel the , pass the wait and cancel functions to the constructor.

Wait function

The wait function must be of type . The wait function provided to a constructor is invoked when the method of the is called. The wait function must resolve the by calling the function passed to it as an argument, or throw an exception.

Cancel function

When creating a you can provide an optional cancel function of type , which is invoked by the promise if you call the method of the promise. The cancel function may optionally reject the promise by invoking the function passed to it as an argument.

FulfilledPromise

The class object is fulfilled on construction.

RejectedPromise

The class object is rejected on construction.

IteratorPromise

The class creates an aggregated promise that iterates over an iterator of promises, or values, and triggers callback functions in the process. Use to create an iterator for a or a .

GeneratorPromise

The class wraps a generator that yields values, or promises.

Create

The class provides helper methods.

Acknowledgements

This project is inspired by Guzzle Promises. However, it has signficant differences in API and implementation, owing to the language and best-practices requirements of Hack.