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()
These are aliases for the corresponding functions in
Pike.DefaultBackend.
Pike.Backend()->call_out(), Pike.Backend()->_do_call_outs(),
Pike.Backend()->find_call_out(), Pike.Backend()->remove_call_out(),
Pike.Backend()->call_out_info()
@@Pike.Annotations.Implements(Pike.__Backend)The class of the DefaultBackend.
Typically something that has inherited __Backend.
__Backend, DefaultBackend
inherit Pike.__Backend : __Backend
Module for handling multiple concurrent events.
The Future and Promise API was inspired by
https://github.com/couchdeveloper/FutureLib.
local variant Future all(array(Future) futures)
local variant Future all(Future ... futures)
JavaScript Promise API equivalent of results().
The returned Future does NOT have any state (eg backend)
propagated from the futures. This must be done by hand.
results(), Promise.depend()
https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
variant Future first_completed(array(Future) futures)
variant local Future first_completed(Future ... futures)
A Future that represents the first
of the futures that completes.
The returned Future does NOT have any state (eg backend)
propagated from the futures. This must be done by hand.
race(), Promise.first_completed()
Future fold(array(Future) futures, mixed initial, function(mixed, mixed, __unknown__ ... :mixed) fun, mixed ... extra)
Return a Future that represents the accumulated results of
applying fun to the results of the futures in turn.
initialInitial value of the accumulator.
funFunction to apply. The first argument is the result of
one of the futures, the second the current accumulated
value, and any further from extra.
If fun throws an error it will fail the Future.
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.
The returned Future does NOT have any state (eg backend)
propagated from the futures. This must be done by hand.
void on_failure(function(mixed:void) f)protected function(mixed:void) Concurrent.global_on_failure
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.
variant local Future race(array(Future) futures)
variant local Future race(Future ... futures)
JavaScript Promise API equivalent of first_completed().
The returned Future does NOT have any state (eg backend)
propagated from the futures. This must be done by hand.
first_completed(), Promise.first_completed()
https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
Future reject(mixed reason)
A new Future that has already failed for the specified reason.
The returned Future does NOT have a backend set.
Future.on_failure(), Promise.failure()
https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
Future resolve(mixed value)
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.
This function can be used to ensure values are futures.
The returned Future does NOT have a backend set.
Future.on_success(), Promise.success()
https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
variant Future results(array(Future) futures)
local variant Future results(Future ... futures)
A Future that represents the array of all the completed futures.
The returned Future does NOT have any state (eg backend)
propagated from the futures. This must be done by hand.
all(), Promise.depend()
Future serialize(array(Future) futures, function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)
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.
The returned Future does NOT have any state (eg backend)
propagated from the futures. This must be done by hand.
traverse()
Future traverse(array(Future) futures, function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)
Return a Future that represents the array of mapping fun
over the results of the completed futures.
The returned Future does NOT have any state (eg backend)
propagated from the futures. This must be done by hand.
serialize()
final void use_backend(int enable)
enable | A |
| A |
Be very careful about running in the backend disabled mode, as it may cause unlimited recursion and reentrancy issues.
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.
(Un)setting this typically alters the order in which some callbacks are called (depending on what happens in a callback).
Future()->set_backend(), Future()->call_callback()
constant Concurrent.STATE_NO_FUTURE
constant Concurrent.STATE_PENDING
constant Concurrent.STATE_FULFILLED
constant Concurrent.STATE_REJECTED
constant Concurrent.STATE_REJECTION_REPORTED
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().
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.
Future, future(), Promise, first_completed(),
race(), results(), all(), fold()
__generic__ mixed ValueType = mixed
This is the type for the value provided by the individual
aggregated Futures.
inherit Promise(< array(ValueType)|ValueType >) : Promise
protected array(mapping(int:ValueType)) Concurrent.AggregatedPromise.dependency_results
| Array | |
| Successful results. |
| Failed results. |
protected void aggregate_cb(mixed value, int idx, mapping(int:mixed)|zero results)
Callback used to aggregate the results from dependencies.
valueValue received from the dependency.
idxIdentification number for the dependency.
resultsEither of the mappings in dependency_results depending on
whether this was a success or a failure callback.
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().
start()
this_program any_results()
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).
The new Promise.
depend(), max_failures()
this_program depend(array(Future) futures)
local variant this_program depend(Future ... futures)
variant Promise depend()
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.
futuresThe list of futures we want to add to the list we depend upon.
The new Promise.
Can be called multiple times to add more.
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.
fold(), first_completed(), max_failures(), min_failures(),
any_results(), Concurrent.results(), Concurrent.all()
this_program first_completed()
It evaluates to the first future that completes of the list of futures it depends upon.
The new Promise.
depend(), Concurrent.first_completed()
this_program fold(mixed initial, function(mixed, mixed, __unknown__ ... :mixed) fun, mixed ... extra)
initialInitial value of the accumulator.
funFunction to apply. The first argument is the result of
one of the futures. The second argument is the current value
of the accumulator.
extraAny extra context needed for fun. They will be provided
as arguments three and onwards when fun is called.
The new Promise.
If fun throws an error it will fail the Future.
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.
depend(), Concurrent.fold()
this_program max_failures(int(-1..) max)
maxSpecifies the maximum number of failures to be accepted in the list of futures this promise depends upon.
-1 means unlimited.
Defaults to 0.
The new Promise.
depend(), min_failures(), any_results()
this_program min_failures(int(0..) min)
minSpecifies the minimum number of failures to be required in
the list of futures this promise depends upon. Defaults
to 0.
The new Promise.
depend(), max_failures()
protected void start()
Start the aggregation of values from dependencies.
This function is called from several functions. These
include on_success(), on_failure(), wait(),
get(), fold() and first_completed().
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().
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.
Promise
__generic__ mixed ValueType = mixed
This is the type for the value provided by the Future.
protected void apply(mixed val, Promise p, function(mixed, __unknown__ ... :mixed) fun, array(mixed) ctx)
Apply fun with val followed by the contents of ctx,
and update p with the result.
protected void apply_filter(ValueType val, Promise p, function(mixed, __unknown__ ... :bool) fun, array(mixed) ctx)
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.
protected void apply_flat(mixed val, Promise p, function(mixed, __unknown__ ... :Future) fun, array(mixed) ctx)
Apply fun with val followed by the contents of ctx,
and update p with the eventual result.
protected void apply_smart(mixed val, Promise p, function(mixed, __unknown__ ... :mixed|Future) fun, array(mixed) ctx)
Apply fun with val followed by the contents of ctx,
and update p with the eventual result.
protected void call_callback(function(:void) cb, mixed ... args)
Call a callback function.
cbCallback function to call.
argsArguments 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().
set_backend(), use_backend()
this_program delay(int|float seconds)
Return a Future that will be fulfilled with the fulfilled
result of this Future, but not until at least seconds have passed.
this_program filter(function(ValueType, __unknown__ ... :bool) fun, mixed ... extra)
This specifies a callback that is only called on success, and allows you to selectively alter the future into a failure.
funFunction 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.
extraAny extra context needed for
fun. They will be provided
as arguments two and onwards when the callback is called.
The new Future.
transform()
local this_program flat_map(function(ValueType, __unknown__ ... :this_program) fun, mixed ... extra)
This is an alias for map_with().
map_with()
ValueType get()
Wait for fulfillment and return the value.
Throws on rejection.
wait(), try_get()
Pike.Backend get_backend()
Get the backend (if any) used to call any callbacks.
This returns the value set by set_backend().
set_backend()
this_program map(function(ValueType, __unknown__ ... :mixed) fun, mixed ... extra)
This specifies a callback that is only called on success, and allows you to alter the future.
funFunction 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.
extraAny extra context needed for
fun. They will be provided
as arguments two and onwards when the callback is called.
The new Future.
This method is used if your fun returns a regular value (i.e.
not a Future).
map_with(), transform(), recover()
this_program map_with(function(ValueType, __unknown__ ... :this_program) fun, mixed ... extra)
This specifies a callback that is only called on success, and allows you to alter the future.
funFunction 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.
extraAny extra context needed for
fun. They will be provided
as arguments two and onwards when the callback is called.
The new Future.
This method is used if your fun returns a Future again.
map(), transform_with(), recover_with(), flat_map
this_program on_await(function(mixed, function(mixed, __unknown__ ... :void)|void:void) cb)
Set both success and failure callbacks.
cbCallback 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.
Used by predef::await(), in which case cb will be
a generator function.
on_success(), on_failure(), predef::await(), predef::throw()
this_program on_failure(function(mixed, __unknown__ ... :void) cb, mixed ... extra)
Register a callback that is to be called on failure.
cbFunction to be called. The first argument will be the
failure result of the Future.
extraAny extra context needed for cb. They will be provided
as arguments two and onwards when cb is called.
cb will always be called from the main backend.
on_success(), query_failure_callbacks()
this_program on_success(function(ValueType, __unknown__ ... :void) cb, mixed ... extra)
Register a callback that is to be called on fulfillment.
cbFunction to be called. The first argument will be the
result of the Future.
extraAny extra context needed for cb. They will be provided
as arguments two and onwards when cb is called.
cb will always be called from the main backend.
on_failure(), query_success_callbacks()
Promise promise_factory()
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.
Promise, set_backend()
array(function(mixed, __unknown__ ... :void)) query_failure_callbacks()
Query the set of active failure callbacks.
Returns an array with callback functions.
on_failure(), query_success_callbacks()
array(function(ValueType, __unknown__ ... :void)) query_success_callbacks()
Query the set of active success callbacks.
Returns an array with callback functions.
on_success(), query_failure_callbacks()
this_program recover(function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)
This specifies a callback that is only called on failure, and allows you to alter the future into a success.
funFunction 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.
extraAny extra context needed for
fun. They will be provided
as arguments two and onwards when the callback is called.
The new Future.
This method is used if your callbacks return a regular value (i.e.
not a Future).
recover_with(), map(), transform()
this_program recover_with(function(mixed, __unknown__ ... :this_program) fun, mixed ... extra)
This specifies a callback that is only called on failure, and allows you to alter the future into a success.
funFunction 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.
extraAny extra context needed for
fun. They will be provided
as arguments two and onwards when the callback is called.
The new Future.
This method is used if your callbacks return a Future again.
recover(), map_with(), transform_with()
void set_backend(Pike.Backend backend)
Set the backend to use for calling any callbacks.
This overides the mode set by use_backend().
get_backend(), use_backend()
this_program then(void|function(ValueType, __unknown__ ... :mixed) onfulfilled, void|function(mixed, __unknown__ ... :mixed) onrejected, mixed ... extra)
JavaScript Promise API close but not identical equivalent
of a combined transform() and transform_with().
onfulfilledFunction 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.
onrejectedFunction 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.
extraAny extra context needed for onfulfilled and
onrejected. They will be provided
as arguments two and onwards when the callbacks are called.
The new Future.
transform(), transform_with(), thencatch(),
on_success(), Promise.success(),
on_failure(), Promise.failure(),
https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
local this_program thencatch(function(mixed, __unknown__ ... :mixed) onrejected, mixed ... extra)
JavaScript Promise API equivalent of a combination of recover()
and recover_with().
onrejectedFunction 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.
extraAny extra context needed for
onrejected. They will be provided
as arguments two and onwards when the callback is called.
The new Future.
recover(), recover_with(), then(), on_failure(),
Promise.failure(),
https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
this_program timeout(int|float seconds)
Return a Future that will either be fulfilled with the fulfilled
result of this Future, or be failed after seconds have expired.
this_program transform(function(ValueType, __unknown__ ... :mixed) success, function(mixed, __unknown__ ... :mixed)|void failure, mixed ... extra)
This specifies callbacks that allow you to alter the future.
successFunction 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.
failureFunction 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.
extraAny extra context needed for
success and failure. They will be provided
as arguments two and onwards when the callbacks are called.
The new Future.
This method is used if your callbacks return a regular value (i.e.
not a Future).
transform_with(), map(), recover()
this_program transform_with(function(ValueType, __unknown__ ... :this_program) success, function(mixed, __unknown__ ... :this_program)|void failure, mixed ... extra)
This specifies callbacks that allow you to alter the future.
successFunction 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.
failureFunction 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.
extraAny extra context needed for
success and failure. They will be provided
as arguments two and onwards when the callbacks are called.
The new Future.
This method is used if your callbacks return a Future again.
transform(), map_with(), recover_with
ValueType|zero try_get()
Return the value if available.
Returns UNDEFINED if the Future is not yet fulfilled.
Throws on rejection.
wait()
this_program wait()
Wait for fulfillment.
get(), try_get()
this_program zip(array(this_program) others)
local variant this_program zip(this_program ... others)
othersThe other futures (results) you want to append.
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.
results()
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().
Future, future()
__generic__ mixed ValueType = mixed
This is the type for the value provided by the inherited Future.
inherit Future(< ValueType >) : Future
Concurrent.Promise Concurrent.Promise(void|function(function(ValueType:void), function(mixed:void), __unknown__ ... :void) executor, mixed ... extra)
Creates a new promise, optionally initialised from a traditional callback
driven method via executor(success, failure, @extra).
https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
this_program failure(mixed value)
Reject the Future value.
valueFailure result of the Future.
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.
try_failure(), success(), on_failure()
Future future()
The future value that we promise.
this_program success(ValueType value)
Fulfill the Future.
valueResult of the Future.
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.
try_success(), try_failure(), failure(), on_success()
local this_program try_failure(mixed value)
Maybe reject the Future value.
valueFailure 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.
failure(), success(), on_failure()
local this_program try_success(ValueType|zero value)
Fulfill the Future if it hasn't been fulfilled or failed already.
valueResult 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.
success(), try_failure(), failure(), on_success()