PromiseTool

class Firstred\PostNL\Util\PromiseTool

Class PromiseTool.

Summary

Methods

• public static queue($assign)

• public static task($task)

• public static promiseFor($value)

• public static rejectionFor($reason)

• public static exceptionFor($reason)

• public static iterFor($value)

• public static inspect($promise)

• public static inspectAll($promises)

• public static unwrap($promises)

• public static all($promises, $recursive)

• public static some($count, $promises)

• public static any($promises)

• public static settle($promises)

• public static each($iterable, $onFulfilled, $onRejected)

• public static eachLimit($iterable, $concurrency, $onFulfilled, $onRejected)

• public static eachLimitAll($iterable, $concurrency, $onFulfilled)

• public static isFulfilled($promise)

• public static isRejected($promise)

• public static isSettled($promise)

Methods

public static Firstred\PostNL\Util\PromiseTool::queue($assign=null)

Get the global task queue used for promise resolution.

This task queue MUST be run in an event loop in order for promises to be

settled asynchronously. It will be automatically run when synchronously

waiting on a promise.

<code>

while ($eventLoop->isRunning()) {

queue()->run();

}

</code>

Parameters:

• $assign (Firstred\PostNL\Util\TaskQueue) optionally specify a new queue instance

Returns:

\Firstred\PostNL\Util\TaskQueue

public static Firstred\PostNL\Util\PromiseTool::task($task)

Adds a function to run in the task queue when it is next `run()` and returns

a promise that is fulfilled or rejected with the result.

Parameters:

• $task (callable) task function to run

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::promiseFor($value)

Creates a promise for a value if the value is not a promise.

Parameters:

• $value (mixed) promise or value

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::rejectionFor($reason)

Creates a rejected promise for a reason if the reason is not a promise. If

the provided reason is a promise, then it is returned as-is.

Parameters:

• $reason (mixed) promise or reason

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::exceptionFor($reason)

Create an exception for a rejected promise value.

Parameters:

• $reason (mixed)

Returns:

\Firstred\PostNL\Util\Throwable

public static Firstred\PostNL\Util\PromiseTool::iterFor($value)

Returns an iterator for the given value.

Parameters:

• $value (mixed)

Returns:

\Iterator

public static Firstred\PostNL\Util\PromiseTool::inspect($promise)

Synchronously waits on a promise to resolve and returns an inspection state

array.

Returns a state associative array containing a “state” key mapping to a

valid promise state. If the state of the promise is “fulfilled”, the array

will contain a “value” key mapping to the fulfilled value of the promise. If

the promise is rejected, the array will contain a “reason” key mapping to

the rejection reason of the promise.

Parameters:

• $promise (Http\Promise\Promise) promise or value

Returns:

array

Throws:

\Exception

public static Firstred\PostNL\Util\PromiseTool::inspectAll($promises)

Waits on all of the provided promises, but does not unwrap rejected promises

as thrown exception.

Returns an array of inspection state arrays.

Parameters:

• $promises (Http\Promise\Promise[]) traversable of promises to wait upon

Returns:

array

Throws:

\Exception

Throws:

\Exception

Throws:

\Exception

Throws:

\Exception

public static Firstred\PostNL\Util\PromiseTool::unwrap($promises)

Waits on all of the provided promises and returns the fulfilled values.

Returns an array that contains the value of each promise (in the same order

the promises were provided). An exception is thrown if any of the promises

are rejected.

Parameters:

• $promises (mixed) iterable of Promise objects to wait on

Returns:

array

Throws:

\Exception on error

Throws:

\Firstred\PostNL\Util\Throwable on error in PHP >=7

Throws:

\Exception on error

Throws:

\Firstred\PostNL\Util\Throwable on error in PHP >=7

public static Firstred\PostNL\Util\PromiseTool::all($promises, $recursive=false)

Given an array of promises, return a promise that is fulfilled when all the

items in the array are fulfilled.

The promise's fulfillment value is an array with fulfillment values at

respective positions to the original array. If any promise in the array

rejects, the returned promise is rejected with the rejection reason.

Parameters:

• $promises (mixed) promises or values

• $recursive (bool) - If true, resolves new promises that might have been added to the stack during its own resolution

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::some($count, $promises)

Initiate a competitive race between multiple promises or values (values will

become immediately fulfilled promises).

When count amount of promises have been fulfilled, the returned promise is

fulfilled with an array that contains the fulfillment values of the winners

in order of resolution.

Parameters:

• $count (int) total number of promises

• $promises (mixed) promises or values

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::any($promises)

Like some(), with 1 as count. However, if the promise fulfills, the

fulfillment value is not an array of 1 but the value directly.

Parameters:

• $promises (mixed) promises or values

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::settle($promises)

Returns a promise that is fulfilled when all of the provided promises have

been fulfilled or rejected.

The returned promise is fulfilled with an array of inspection state arrays.

Parameters:

• $promises (mixed) promises or values

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::each($iterable, $onFulfilled=null, $onRejected=null)

Given an iterator that yields promises or values, returns a promise that is

fulfilled with a null value when the iterator has been consumed or the

aggregate promise has been fulfilled or rejected.

$onFulfilled is a function that accepts the fulfilled value, iterator

index, and the aggregate promise. The callback can invoke any necessary side

effects and choose to resolve or reject the aggregate promise if needed.

$onRejected is a function that accepts the rejection reason, iterator

index, and the aggregate promise. The callback can invoke any necessary side

effects and choose to resolve or reject the aggregate promise if needed.

Parameters:

• $iterable (mixed) iterator or array to iterate over

• $onFulfilled (callable)

• $onRejected (callable)

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::eachLimit($iterable, $concurrency, $onFulfilled=null, $onRejected=null)

Like each, but only allows a certain number of outstanding promises at any

given time.

$concurrency may be an integer or a function that accepts the number of

pending promises and returns a numeric concurrency limit value to allow for

dynamic a concurrency size.

Parameters:

• $iterable (mixed)

• $concurrency (int | callable)

• $onFulfilled (callable)

• $onRejected (callable)

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::eachLimitAll($iterable, $concurrency, $onFulfilled=null)

Like each_limit, but ensures that no promise in the given $iterable argument

is rejected. If any promise is rejected, then the aggregate promise is

rejected with the encountered rejection.

Parameters:

• $iterable (mixed)

• $concurrency (int | callable)

• $onFulfilled (callable)

Returns:

\Http\Promise\Promise

public static Firstred\PostNL\Util\PromiseTool::isFulfilled($promise)

Returns true if a promise is fulfilled.

Parameters:

• $promise (Http\Promise\Promise)

Returns:

bool

public static Firstred\PostNL\Util\PromiseTool::isRejected($promise)

Returns true if a promise is rejected.

Parameters:

• $promise (Http\Promise\Promise)

Returns:

bool

public static Firstred\PostNL\Util\PromiseTool::isSettled($promise)

Returns true if a promise is fulfilled or rejected.

Parameters:

• $promise (Http\Promise\Promise)

Returns:

bool