Skip to content

Please, clarify description of Future.whenComplete() #29338

Open
@alsemenov

Description

@alsemenov

The description of method Future.whenComplete() reads:

Future whenComplete(
dynamic action()
)
Register a function to be called when this future completes.

The action function is called when this future completes, whether it does so with a value or with an error.

This is the asynchronous equivalent of a "finally" block.

The future returned by this call, f, will complete the same way as this future unless an error occurs in the action call, or in a Future returned by the action call. If the call to action does not return a future, its return value is ignored.

If the call to action throws, then f is completed with the thrown error.

If the call to action returns a Future, f2, then completion of f is delayed until f2 completes. If f2 completes with an error, that will be the result of f too. The value of f2 is always ignored.

This method is equivalent to:

Future<T> whenComplete(action()) {
  return this.then((v) {
    var f2 = action();
    if (f2 is Future) return f2.then((_) => v);
    return v
  }, onError: (e) {
    var f2 = action();
    if (f2 is Future) return f2.then((_) { throw e; });
    throw e;
  });
}

Please, clarify when the action will be called? Is it guaranteed that action will be called after all future callbacks complete? (like finally is executed when all error handlers are executed)
According to #29168 and given source code, I believe, there is no such guarantees.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2A bug or feature request we're likely to work onarea-core-librarySDK core library issues (core, async, ...); use area-vm or area-web for platform specific libraries.core-alibrary-asynctype-documentationA request to add or improve documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions