19. Asynchronous Operation

19.1. Backends


Method call_out
Method _do_call_outs
Method find_call_out
Method remove_call_out
Method call_out_info

mixed call_out(function(:void) f, float|int delay, mixed ... args)
void _do_call_outs()
int find_call_out(function(:void) f)
int find_call_out(mixed id)
int remove_call_out(function(:void) f)
int remove_call_out(function(:void) id)
array(array) call_out_info()

Description

These are aliases for the corresponding functions in Pike.DefaultBackend.

See also

Pike.Backend()->call_out(), Pike.Backend()->_do_call_outs(), Pike.Backend()->find_call_out(), Pike.Backend()->remove_call_out(), Pike.Backend()->call_out_info()

Class Pike.Backend

Annotations
@@Pike.Annotations.Implements(Pike.__Backend)
Description

The class of the DefaultBackend.

Typically something that has inherited __Backend.

See also

__Backend, DefaultBackend


Inherit __Backend

inherit Pike.__Backend : __Backend

19.2. Promises and Futures

Module Concurrent

Description

Module for handling multiple concurrent events.

The Future and Promise API was inspired by https://github.com/couchdeveloper/FutureLib.


Method all

local variant Future all(array(Future) futures)
local variant Future all(Future ... futures)

Description

JavaScript Promise API equivalent of results().

Note

The returned Future does NOT have any state (eg backend) propagated from the futures. This must be done by hand.

See also

results(), Promise.depend() https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise


Method first_completed

variant Future first_completed(array(Future) futures)
variant local Future first_completed(Future ... futures)

Returns

A Future that represents the first of the futures that completes.

Note

The returned Future does NOT have any state (eg backend) propagated from the futures. This must be done by hand.

See also

race(), Promise.first_completed()


Method fold

Future fold(array(Future) futures, mixed initial, function(mixed, mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Description

Return a Future that represents the accumulated results of applying fun to the results of the futures in turn.

Parameter initial

Initial value of the accumulator.

Parameter fun

Function to apply. The first argument is the result of one of the futures, the second the current accumulated value, and any further from extra.

Note

If fun throws an error it will fail the Future.

Note

fun may be called in any order, and will be called once for every Future in futures, unless one of calls fails in which case no further calls will be performed.

Note

The returned Future does NOT have any state (eg backend) propagated from the futures. This must be done by hand.


Syntax

void on_failure(function(mixed:void) f)protected function(mixed:void) Concurrent.global_on_failure

Description

Global failure callback, called when a promise without failure callback fails. This is useful to log exceptions, so they are not just silently caught and ignored.


Method race

variant local Future race(array(Future) futures)
variant local Future race(Future ... futures)

Description

JavaScript Promise API equivalent of first_completed().

Note

The returned Future does NOT have any state (eg backend) propagated from the futures. This must be done by hand.

See also

first_completed(), Promise.first_completed() https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise


Method reject

Future reject(mixed reason)

Returns

A new Future that has already failed for the specified reason.

Note

The returned Future does NOT have a backend set.

See also

Future.on_failure(), Promise.failure() https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise


Method resolve

Future resolve(mixed value)

Returns

A new Future that has already been fulfilled with value as result. If value is an object which already has on_failure and on_success methods, return it unchanged.

Note

This function can be used to ensure values are futures.

Note

The returned Future does NOT have a backend set.

See also

Future.on_success(), Promise.success() https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise


Method results

variant Future results(array(Future) futures)
local variant Future results(Future ... futures)

Returns

A Future that represents the array of all the completed futures.

Note

The returned Future does NOT have any state (eg backend) propagated from the futures. This must be done by hand.

See also

all(), Promise.depend()


Method serialize

Future serialize(array(Future) futures, function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Description

Return a Future that represents the array of mapping fun sequentially over the results of the completed futures.

This function differs from traverse() in that only one call of fun will be active at a time. This is useful when each call of fun uses lots of resources, but may increase latency.

If fun() fails for one of the items, it will not be called for any others.

Note

The returned Future does NOT have any state (eg backend) propagated from the futures. This must be done by hand.

See also

traverse()


Method traverse

Future traverse(array(Future) futures, function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Description

Return a Future that represents the array of mapping fun over the results of the completed futures.

Note

The returned Future does NOT have any state (eg backend) propagated from the futures. This must be done by hand.

See also

serialize()


Method use_backend

final void use_backend(int enable)

Parameter enable
0

A false value causes all Concurrent callbacks (except for timeouts) to default to being called directly, without using a backend.

1

A true value causes callbacks to default to being called via Pike.DefaultBackend.

Note

Be very careful about running in the backend disabled mode, as it may cause unlimited recursion and reentrancy issues.

Note

As long as the backend hasn't started, it will default to false. Upon startup of the backend, it will change to true unless you explicitly called use_backend() before that.

Note

(Un)setting this typically alters the order in which some callbacks are called (depending on what happens in a callback).

See also

Future()->set_backend(), Future()->call_callback()

Enum Concurrent.State


Constant STATE_NO_FUTURE
Constant STATE_PENDING
Constant STATE_FULFILLED
Constant STATE_REJECTED
Constant STATE_REJECTION_REPORTED

constant Concurrent.STATE_NO_FUTURE
constant Concurrent.STATE_PENDING
constant Concurrent.STATE_FULFILLED
constant Concurrent.STATE_REJECTED
constant Concurrent.STATE_REJECTION_REPORTED

Class Concurrent.AggregatedPromise (< ValueType >)

Description

Promise to provide an aggregated Future value.

Objects of this class are typically kept internal to the code that provides the Future value. The only thing that is directly returned to the user is the return value from future().

Note

It is currently possible to use this class as a normal Promise (ie without aggregation), but those functions may get removed in a future version of Pike. Functions to avoid include success() and try_success(). If you do not need aggregation use Promise.

See also

Future, future(), Promise, first_completed(), race(), results(), all(), fold()


Generic ValueType

__generic__ mixed ValueType = mixed

Description

This is the type for the value provided by the individual aggregated Futures.


Inherit Promise

inherit Promise(< array(ValueType)|ValueType >) : Promise


Variable dependency_results

protected array(mapping(int:ValueType)) Concurrent.AggregatedPromise.dependency_results

Description
Array
mapping(int:mixed) 0

Successful results.

mapping(int:mixed) 1

Failed results.


Method aggregate_cb

protected void aggregate_cb(mixed value, int idx, mapping(int:mixed)|zero results)

Description

Callback used to aggregate the results from dependencies.

Parameter value

Value received from the dependency.

Parameter idx

Identification number for the dependency.

Parameter results

Either of the mappings in dependency_results depending on whether this was a success or a failure callback.

Note

The function may also be called with all arguments set to UNDEFINED in order to poll the current state. This is typically done via a call to start().

See also

start()


Method any_results

this_program any_results()

Description

Sets the number of failures to be accepted in the list of futures this promise depends upon to unlimited. It is equivalent to max_failures(-1).

Returns

The new Promise.

See also

depend(), max_failures()


Method depend

this_program depend(array(Future) futures)
local variant this_program depend(Future ... futures)
variant this_program depend()

Description

Add futures to the list of futures which the current object depends upon.

If called without arguments it will produce a new Future from a new Promise which is implictly added to the dependency list.

Parameter futures

The list of futures we want to add to the list we depend upon.

Returns

The new Promise.

Note

Can be called multiple times to add more.

Note

Once the promise has been materialised (when either on_success(), on_failure() or get() has been called on this object), it is not possible to call depend() anymore.

See also

fold(), first_completed(), max_failures(), min_failures(), any_results(), Concurrent.results(), Concurrent.all()


Method first_completed

this_program first_completed()

Description

It evaluates to the first future that completes of the list of futures it depends upon.

Returns

The new Promise.

See also

depend(), Concurrent.first_completed()


Method fold

this_program fold(mixed initial, function(mixed, mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Parameter initial

Initial value of the accumulator.

Parameter fun

Function to apply. The first argument is the result of one of the futures. The second argument is the current value of the accumulator.

Parameter extra

Any extra context needed for fun. They will be provided as arguments three and onwards when fun is called.

Returns

The new Promise.

Note

If fun throws an error it will fail the Future.

Note

fun may be called in any order, and will be called once for every Future it depends upon, unless one of the calls fails in which case no further calls will be performed.

See also

depend(), Concurrent.fold()


Method max_failures

this_program max_failures(int(-1..) max)

Parameter max

Specifies the maximum number of failures to be accepted in the list of futures this promise depends upon.

-1 means unlimited.

Defaults to 0.

Returns

The new Promise.

See also

depend(), min_failures(), any_results()


Method min_failures

this_program min_failures(int(0..) min)

Parameter min

Specifies the minimum number of failures to be required in the list of futures this promise depends upon. Defaults to 0.

Returns

The new Promise.

See also

depend(), max_failures()


Method start

protected void start()

Description

Start the aggregation of values from dependencies.

Note

This function is called from several functions. These include on_success(), on_failure(), wait(), get(), fold() and first_completed().

Note

After this function has been called, several functions may no longer be called. These include depend(), fold(), first_completed(), max_failures(), min_failures(), any_results().

Class Concurrent.Future (< ValueType >)

Description

Value that will be provided asynchronously sometime in the future. A Future object is typically produced from a Promise object by calling its future() method.

See also

Promise


Generic ValueType

__generic__ mixed ValueType = mixed

Description

This is the type for the value provided by the Future.


Method apply

protected void apply(mixed val, Promise p, function(mixed, __unknown__ ... :mixed) fun, array(mixed) ctx)

Description

Apply fun with val followed by the contents of ctx, and update p with the result.


Method apply_filter

protected void apply_filter(ValueType val, Promise p, function(mixed, __unknown__ ... :bool) fun, array(mixed) ctx)

Description

Apply fun with val followed by the contents of ctx, and update p with val if fun didn't return false. If fun returned false, fail p with 0 as result.


Method apply_flat

protected void apply_flat(mixed val, Promise p, function(mixed, __unknown__ ... :Future) fun, array(mixed) ctx)

Description

Apply fun with val followed by the contents of ctx, and update p with the eventual result.


Method apply_smart

protected void apply_smart(mixed val, Promise p, function(mixed, __unknown__ ... :mixed|Future) fun, array(mixed) ctx)

Description

Apply fun with val followed by the contents of ctx, and update p with the eventual result.


Method call_callback

protected void call_callback(function(:void) cb, mixed ... args)

Description

Call a callback function.

Parameter cb

Callback function to call.

Parameter args

Arguments to call cb with.

The default implementation calls cb via the backend set via set_backend() (if any), and otherwise falls back the the mode set by use_backend().

See also

set_backend(), use_backend()


Method delay

this_program delay(int|float seconds)

Description

Return a Future that will be fulfilled with the fulfilled result of this Future, but not until at least seconds have passed.


Method filter

this_program filter(function(ValueType, __unknown__ ... :bool) fun, mixed ... extra)

Description

This specifies a callback that is only called on success, and allows you to selectively alter the future into a failure.

Parameter fun

Function to be called. The first argument will be the success result of this Future. If the return value is true, the future succeeds with the original success result. If the return value is false, the future fails with an UNDEFINED result.

Parameter extra

Any extra context needed for fun. They will be provided as arguments two and onwards when the callback is called.

Returns

The new Future.

See also

transform()


Method flat_map

local this_program flat_map(function(ValueType, __unknown__ ... :this_program) fun, mixed ... extra)

Description

This is an alias for map_with().

See also

map_with()


Method get

ValueType get()

Description

Wait for fulfillment and return the value.

Throws

Throws on rejection.

See also

wait(), try_get()


Method get_backend

Pike.Backend get_backend()

Description

Get the backend (if any) used to call any callbacks.

This returns the value set by set_backend().

See also

set_backend()


Method map

this_program map(function(ValueType, __unknown__ ... :mixed) fun, mixed ... extra)

Description

This specifies a callback that is only called on success, and allows you to alter the future.

Parameter fun

Function to be called. The first argument will be the success result of this Future. The return value will be the success result of the new Future.

Parameter extra

Any extra context needed for fun. They will be provided as arguments two and onwards when the callback is called.

Returns

The new Future.

Note

This method is used if your fun returns a regular value (i.e. not a Future).

See also

map_with(), transform(), recover()


Method map_with

this_program map_with(function(ValueType, __unknown__ ... :this_program) fun, mixed ... extra)

Description

This specifies a callback that is only called on success, and allows you to alter the future.

Parameter fun

Function to be called. The first argument will be the success result of this Future. The return value must be a Future that promises the new result.

Parameter extra

Any extra context needed for fun. They will be provided as arguments two and onwards when the callback is called.

Returns

The new Future.

Note

This method is used if your fun returns a Future again.

See also

map(), transform_with(), recover_with(), flat_map


Method on_await

this_program on_await(function(mixed, function(mixed, __unknown__ ... :void)|void:void) cb)

Description

Set both success and failure callbacks.

Parameter cb

Callback to call with the success value on success.

On failure it is called with two arguments; the failure value and predef::throw as the second argument.

Note

Used by predef::await(), in which case cb will be a generator function.

See also

on_success(), on_failure(), predef::await(), predef::throw()


Method on_failure

this_program on_failure(function(mixed, __unknown__ ... :void) cb, mixed ... extra)

Description

Register a callback that is to be called on failure.

Parameter cb

Function to be called. The first argument will be the failure result of the Future.

Parameter extra

Any extra context needed for cb. They will be provided as arguments two and onwards when cb is called.

Note

cb will always be called from the main backend.

See also

on_success(), query_failure_callbacks()


Method on_success

this_program on_success(function(ValueType, __unknown__ ... :void) cb, mixed ... extra)

Description

Register a callback that is to be called on fulfillment.

Parameter cb

Function to be called. The first argument will be the result of the Future.

Parameter extra

Any extra context needed for cb. They will be provided as arguments two and onwards when cb is called.

Note

cb will always be called from the main backend.

See also

on_failure(), query_success_callbacks()


Method promise_factory

Promise promise_factory()

Description

Create a new Promise with the same base settings as the current object.

Overload this function if you need to propagate more state to new Promise objects.

The default implementation copies the backend setting set with set_backend() to the new Promise.

See also

Promise, set_backend()


Method query_failure_callbacks

array(function(mixed, __unknown__ ... :void)) query_failure_callbacks()

Description

Query the set of active failure callbacks.

Returns

Returns an array with callback functions.

See also

on_failure(), query_success_callbacks()


Method query_success_callbacks

array(function(ValueType, __unknown__ ... :void)) query_success_callbacks()

Description

Query the set of active success callbacks.

Returns

Returns an array with callback functions.

See also

on_success(), query_failure_callbacks()


Method recover

this_program recover(function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Description

This specifies a callback that is only called on failure, and allows you to alter the future into a success.

Parameter fun

Function to be called. The first argument will be the failure result of this Future. The return value will be the success result of the new Future.

Parameter extra

Any extra context needed for fun. They will be provided as arguments two and onwards when the callback is called.

Returns

The new Future.

Note

This method is used if your callbacks return a regular value (i.e. not a Future).

See also

recover_with(), map(), transform()


Method recover_with

this_program recover_with(function(mixed, __unknown__ ... :this_program) fun, mixed ... extra)

Description

This specifies a callback that is only called on failure, and allows you to alter the future into a success.

Parameter fun

Function to be called. The first argument will be the failure result of this Future. The return value must be a Future that promises the new success result.

Parameter extra

Any extra context needed for fun. They will be provided as arguments two and onwards when the callback is called.

Returns

The new Future.

Note

This method is used if your callbacks return a Future again.

See also

recover(), map_with(), transform_with()


Method set_backend

void set_backend(Pike.Backend backend)

Description

Set the backend to use for calling any callbacks.

Note

This overides the mode set by use_backend().

See also

get_backend(), use_backend()


Method then

this_program then(void|function(ValueType, __unknown__ ... :mixed) onfulfilled, void|function(mixed, __unknown__ ... :mixed) onrejected, mixed ... extra)

Description

JavaScript Promise API close but not identical equivalent of a combined transform() and transform_with().

Parameter onfulfilled

Function to be called on fulfillment. The first argument will be the result of this Future. The return value will be the result of the new Future. If the return value already is a Future, pass it as-is.

Parameter onrejected

Function to be called on failure. The first argument will be the failure result of this Future. The return value will be the failure result of the new Future. If the return value already is a Future, pass it as-is.

Parameter extra

Any extra context needed for onfulfilled and onrejected. They will be provided as arguments two and onwards when the callbacks are called.

Returns

The new Future.

See also

transform(), transform_with(), thencatch(), on_success(), Promise.success(), on_failure(), Promise.failure(), https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise


Method thencatch

local this_program thencatch(function(mixed, __unknown__ ... :mixed) onrejected, mixed ... extra)

Description

JavaScript Promise API equivalent of a combination of recover() and recover_with().

Parameter onrejected

Function to be called. The first argument will be the failure result of this Future. The return value will the failure result of the new Future. If the return value already is a Future, pass it as-is.

Parameter extra

Any extra context needed for onrejected. They will be provided as arguments two and onwards when the callback is called.

Returns

The new Future.

See also

recover(), recover_with(), then(), on_failure(), Promise.failure(), https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise


Method timeout

this_program timeout(int|float seconds)

Description

Return a Future that will either be fulfilled with the fulfilled result of this Future, or be failed after seconds have expired.


Method transform

this_program transform(function(ValueType, __unknown__ ... :mixed) success, function(mixed, __unknown__ ... :mixed)|void failure, mixed ... extra)

Description

This specifies callbacks that allow you to alter the future.

Parameter success

Function to be called. The first argument will be the success result of this Future. The return value will be the success result of the new Future.

Parameter failure

Function to be called. The first argument will be the failure result of this Future. The return value will be the success result of the new Future. If this callback is omitted, it will default to the same callback as success.

Parameter extra

Any extra context needed for success and failure. They will be provided as arguments two and onwards when the callbacks are called.

Returns

The new Future.

Note

This method is used if your callbacks return a regular value (i.e. not a Future).

See also

transform_with(), map(), recover()


Method transform_with

this_program transform_with(function(ValueType, __unknown__ ... :this_program) success, function(mixed, __unknown__ ... :this_program)|void failure, mixed ... extra)

Description

This specifies callbacks that allow you to alter the future.

Parameter success

Function to be called. The first argument will be the success result of this Future. The return value must be a Future that promises the new result.

Parameter failure

Function to be called. The first argument will be the failure result of this Future. The return value must be a Future that promises the new success result. If this callback is omitted, it will default to the same callback as success.

Parameter extra

Any extra context needed for success and failure. They will be provided as arguments two and onwards when the callbacks are called.

Returns

The new Future.

Note

This method is used if your callbacks return a Future again.

See also

transform(), map_with(), recover_with


Method try_get

ValueType|zero try_get()

Description

Return the value if available.

Returns

Returns UNDEFINED if the Future is not yet fulfilled.

Throws

Throws on rejection.

See also

wait()


Method wait

this_program wait()

Description

Wait for fulfillment.

See also

get(), try_get()


Method zip

this_program zip(array(this_program) others)
local variant this_program zip(this_program ... others)

Parameter others

The other futures (results) you want to append.

Returns

A new Future that will be fulfilled with an array of the fulfilled result of this object followed by the fulfilled results of other futures.

See also

results()

Class Concurrent.Promise (< ValueType >)

Description

Promise to provide a Future value.

Objects of this class are typically kept internal to the code that provides the Future value. The only thing that is directly returned to the user is the return value from future().

See also

Future, future()


Generic ValueType

__generic__ mixed ValueType = mixed

Description

This is the type for the value provided by the inherited Future.


Inherit Future

inherit Future(< ValueType >) : Future


Method create

Concurrent.Promise Concurrent.Promise(void|function(function(ValueType:void), function(mixed:void), __unknown__ ... :void) executor, mixed ... extra)

Description

Creates a new promise, optionally initialised from a traditional callback driven method via executor(success, failure, @extra).

See also

https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise


Method failure

this_program failure(mixed value)

Description

Reject the Future value.

Parameter value

Failure result of the Future.

Throws

Throws an error if the Future already has been fulfilled or failed.

Mark the Future as failed, and schedule the on_failure() callbacks to be called as soon as possible.

See also

try_failure(), success(), on_failure()


Method future

Future future()

Description

The future value that we promise.


Method success

this_program success(ValueType value)

Description

Fulfill the Future.

Parameter value

Result of the Future.

Throws

Throws an error if the Future already has been fulfilled or failed.

Mark the Future as fulfilled, and schedule the on_success() callbacks to be called as soon as possible.

See also

try_success(), try_failure(), failure(), on_success()


Method try_failure

local this_program try_failure(mixed value)

Description

Maybe reject the Future value.

Parameter value

Failure result of the Future.

Mark the Future as failed if it hasn't already been fulfilled, and in that case schedule the on_failure() callbacks to be called as soon as possible.

See also

failure(), success(), on_failure()


Method try_success

local this_program try_success(ValueType|zero value)

Description

Fulfill the Future if it hasn't been fulfilled or failed already.

Parameter value

Result of the Future.

Mark the Future as fulfilled if it hasn't already been fulfilled or failed, and in that case schedule the on_success() callbacks to be called as soon as possible.

See also

success(), try_failure(), failure(), on_success()