Pike Manual

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

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

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

19. Asynchronous Operation

19.1. Backends

Class Pike.Backend

19.2. Promises and Futures

Module Concurrent

Enum Concurrent.State

Class Concurrent.AggregatedPromise (< ValueType >)

Class Concurrent.Future (< ValueType >)

Class Concurrent.Promise (< ValueType >)