Future<T> Interface
A Future is used to obtain a value sometime in the future. Receivers of a Future can obtain the value by passing a callback to then. For example:
Future<int> future = getFutureFromSomewhere();
future.then((value) {
print("I received the number $value");
});
A future may complete by succeeding (producing a value) or failing (producing an exception, which may be handled with handleException). Callbacks passed to onComplete will be invoked in either case.
When a future completes, the following actions happen in order:
- if the future suceeded, handlers registered with then are called.
-
if the future failed, handlers registered with handleException are called in sequence, until one returns true.
- handlers registered with onComplete are called
-
if the future failed, and at least one handler was registered with then, and no handler registered with handleException returned
true, then the exception is thrown.
Default class
Implemented by
Constructors
Code new Future.immediate(T value) #
A future whose value is immediately available.
Future.immediate(T value);
Methods
Code Future chain(Future transformation(T value)) #
A future representing an asynchronous transformation applied to this future's value. transformation must return a Future.
When this future gets a value, transformation will be called on the value. When the resulting future gets a value, the returned future will receive it.
If an exception occurs (received by this future, thrown by transformation, or received by the future returned by transformation) then the returned future will receive the exception.
You must not add exception handlers to this future prior to calling
chain, and any you add afterwards will not be invoked.
Future chain(Future transformation(T value));
Code Object get exception() #
Exception that occurred (null if no exception occured). This property
throws a FutureNotCompleteException if it is used before this future is
completes.
Object get exception();
Code void handleException(bool onException(Object exception)) #
If this future is complete and has an exception, then call onException.
If onException returns true, then the exception is considered handled.
If onException does not return true (or handleException was never called), then the exception is not considered handled. In that case, if there were any calls to then, then the exception will be thrown when the value is set.
In most cases it should not be necessary to call handleException, because the exception associated with this Future will propagate naturally if the future's value is being consumed. Only call handleException if you need to do some special local exception handling related to this particular Future's value.
void handleException(bool onException(Object exception));
Code bool get hasValue() #
Whether the value is available (meaning isComplete is true, and there was no exception).
bool get hasValue();
Code bool get isComplete() #
Whether the future is complete (either the value is available or there was an exception).
bool get isComplete();
Code void onComplete(void complete(Future<T> future)) #
When this future is complete (either with a value or with an exception), then complete is called with the future. If complete throws an exception, it is ignored.
void onComplete(void complete(Future<T> future));
Code Object get stackTrace() #
The stack trace object associated with the exception that occurred. This
throws a FutureNotCompleteException if it is used before the future
completes. Returns null if the future completed successfully or a
stack trace wasn't provided with the exception when it occurred.
Object get stackTrace();
Code void then(void onSuccess(T value)) #
If this future is complete and has a value, then onValue is called
with the value.
void then(void onSuccess(T value));
Code Future transform(transformation(T value)) #
A future representing transformation applied to this future's value.
When this future gets a value, transformation will be called on the value, and the returned future will receive the result.
If an exception occurs (received by this future, or thrown by transformation) then the returned future will receive the exception.
You must not add exception handlers to this future prior to calling
transform, and any you add afterwards will not be invoked.
Future transform(transformation(T value));