19. Asynchronous Operation

19.1. Backends


Methodcall_out
Method_do_call_outs
Methodfind_call_out
Methodremove_call_out
Methodcall_out_info

mixedcall_out(function(:void) f, float|intdelay, mixed ... args)
void_do_call_outs()
intfind_call_out(function(:void) f)
intfind_call_out(mixedid)
intremove_call_out(function(:void) f)
intremove_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.


Methodall

localvariantFutureall(array(Future) futures)
localvariantFutureall(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


Methodfirst_completed

variantFuturefirst_completed(array(Future) futures)
variantlocalFuturefirst_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()


Methodfold

Futurefold(array(Future) futures, mixedinitial, 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

voidon_failure(function(mixed:void) f)protectedfunction(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.


Methodrace

variantlocalFuturerace(array(Future) futures)
variantlocalFuturerace(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


Methodreject

Futurereject(mixedreason)

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


Methodresolve

Futureresolve(mixedvalue)

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


Methodresults

variantFutureresults(array(Future) futures)
localvariantFutureresults(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()


Methodserialize

Futureserialize(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()


Methodtraverse

Futuretraverse(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()


Methoduse_backend

finalvoiduse_backend(intenable)

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


ConstantSTATE_NO_FUTURE
ConstantSTATE_PENDING
ConstantSTATE_FULFILLED
ConstantSTATE_REJECTED
ConstantSTATE_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()


GenericValueType

__generic__mixedValueType = mixed

Description

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


InheritPromise

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


Variabledependency_results

protectedarray(mapping(int:ValueType)) Concurrent.AggregatedPromise.dependency_results

Description
Array
mapping(int:mixed) 0

Successful results.

mapping(int:mixed) 1

Failed results.


Methodaggregate_cb

protectedvoidaggregate_cb(mixedvalue, intidx, mapping(int:mixed)|zeroresults)

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()


Methodany_results

this_programany_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()


Methoddepend

this_programdepend(array(Future) futures)
localvariantthis_programdepend(Future ... futures)
variantPromisedepend()

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()


Methodfirst_completed

this_programfirst_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()


Methodfold

this_programfold(mixedinitial, 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()


Methodmax_failures

this_programmax_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()


Methodmin_failures

this_programmin_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()


Methodstart

protectedvoidstart()

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


GenericValueType

__generic__mixedValueType = mixed

Description

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


Methodapply

protectedvoidapply(mixedval, Promisep, 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.


Methodapply_filter

protectedvoidapply_filter(ValueTypeval, Promisep, 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.


Methodapply_flat

protectedvoidapply_flat(mixedval, Promisep, 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.


Methodapply_smart

protectedvoidapply_smart(mixedval, Promisep, 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.


Methodcall_callback

protectedvoidcall_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()


Methoddelay

this_programdelay(int|floatseconds)

Description

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


Methodfilter

this_programfilter(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 thisFuture. 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()


Methodflat_map

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

Description

This is an alias for map_with().

See also

map_with()


Methodget

ValueTypeget()

Description

Wait for fulfillment and return the value.

Throws

Throws on rejection.

See also

wait(), try_get()


Methodget_backend

Pike.Backendget_backend()

Description

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

This returns the value set by set_backend().

See also

set_backend()


Methodmap

this_programmap(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 thisFuture. 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()


Methodmap_with

this_programmap_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 thisFuture. 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


Methodon_await

this_programon_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()


Methodon_failure

this_programon_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()


Methodon_success

this_programon_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()


Methodpromise_factory

Promisepromise_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()


Methodquery_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()


Methodquery_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()


Methodrecover

this_programrecover(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 thisFuture. 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()


Methodrecover_with

this_programrecover_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 thisFuture. 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()


Methodset_backend

voidset_backend(Pike.Backendbackend)

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()


Methodthen

this_programthen(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 thisFuture. 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 thisFuture. 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


Methodthencatch

localthis_programthencatch(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 thisFuture. 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


Methodtimeout

this_programtimeout(int|floatseconds)

Description

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


Methodtransform

this_programtransform(function(ValueType, __unknown__ ... :mixed) success, function(mixed, __unknown__ ... :mixed)|voidfailure, 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 thisFuture. 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 thisFuture. 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()


Methodtransform_with

this_programtransform_with(function(ValueType, __unknown__ ... :this_program) success, function(mixed, __unknown__ ... :this_program)|voidfailure, 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 thisFuture. 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 thisFuture. 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


Methodtry_get

ValueType|zerotry_get()

Description

Return the value if available.

Returns

Returns UNDEFINED if the Future is not yet fulfilled.

Throws

Throws on rejection.

See also

wait()


Methodwait

this_programwait()

Description

Wait for fulfillment.

See also

get(), try_get()


Methodzip

this_programzip(array(this_program) others)
localvariantthis_programzip(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()


GenericValueType

__generic__mixedValueType = mixed

Description

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


InheritFuture

inherit Future(< ValueType >) : Future


Methodcreate

Concurrent.PromiseConcurrent.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


Methodfailure

this_programfailure(mixedvalue)

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()


Methodfuture

Futurefuture()

Description

The future value that we promise.


Methodsuccess

this_programsuccess(ValueTypevalue)

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()


Methodtry_failure

localthis_programtry_failure(mixedvalue)

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()


Methodtry_success

localthis_programtry_success(ValueType|zerovalue)

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()