Future

A _Future has the following states:

• Incomplete: Maybe be completed, holds listeners.

• Pending complete: Holds listeners

  • Incomplete and Pending both allow adding listeners to the object.

• Chained: Holds a future whose result will be this future's result.

• Value: Is complete, holds value.

• Error: Is complete, holds AsyncError The checks _mayAddListener (incomplete or pending complete), _isChained and _isComplete (value or error) exhausts all the states. These are represented by the following bits in the _state field along with a flag to allow unhandled errors. _Future states have the following transitions: When completing with a non-native Future or starting an async complete.

• incomplete -> pending complete If a pending complete fails synchronously because of a mal-implemented Future.then.

• pending complete -> incomplete. When completing with a native _Future.

• incomplete -> chained

  • listeners in _resultOrListeners are moved to the chain source future.
  • chain source future is stored in _resultOrListeners. When completing synchronously with a value or error.

• incomplete -> completed (aka: value or error)

  • listeners in _resultOrListeners are extracted, and notified of the result. When a delayed async complete happens, or a non-native future completes with the needed value.

• pending complete -> completed

  • listeners in _resultOrListeners are extracted, and notified of the result. When a chained future recognizes that the future it's chained to has completed with an error or value. (May never happen, new listeners on the chained future are forwarded to the chain target future.)

• chained -> completed

  • The result (value or error) and state of the completed chain source future is copied into this future. Public operations checks that the current state is one that allows the requested operation. There is no transition between "pending complete" and "chained", because such a transition is never needed, and no transition out of "completed".