A Completer is used to produce Futures and supply their value when it becomes available.

A service that provides values to callers, and wants to return Futures can use a Completer as follows:

Completer completer = new Completer();
// send future object back to client...
return completer.future;
...

// later when value is available, call:
completer.complete(value);

// alternatively, if the service cannot produce the value, it
// can provide an exception:
completer.completeException(exception);

abstract class Completer<T> {

  factory Completer() => new _CompleterImpl<T>();

  /** The future that will contain the value produced by this completer. */
  Future get future;

  /** Supply a value for [future]. */
  void complete(T value);

  /**
   * Indicate in [future] that an exception occured while trying to produce its
   * value. The argument [exception] should not be [:null:]. A [stackTrace]
   * object can be provided as well to give the user information about where
   * the error occurred. If omitted, it will be [:null:].
   */
  void completeException(Object exception, [Object stackTrace]);
}