Add `FutureOr<T>` class to `dart:async`.

sdk/lib/async/future.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.async;
 
+/// A type representing values that are either `Future<T>` or `T`.
+///
+/// This class declaration is a public stand-in for an internal
+/// future-or-value type. References to this class are resolved to the

[Lasse Reichstein Nielsen, 2016/12/08 16:46:52]

Technically (ob-xkcd 1475) it's not a *type*, it's a *type constructor*, or as
we normally say, a "generic type". It won't be a type until you apply a type
argument.

[floitsch, 2016/12/09 18:19:48]

Done.

+/// internal type.
+///
+/// It is a compile-time error for any class to extend, mix in or implement
+/// `FutureOr`.
+///
+/// Note: the `FutureOr<T>` type is interpreted as `dynamic` in non strong-mode.
+///
+/// # Examples
+/// ``` dart
+/// // The `Future<T>.then` function takes a callback [f] that returns either
+/// // an `S` or a `Future<S>`.
+/// Future<S> then<S>(FutureOr<S> f(T x), ...);
+///
+/// // `Completer<T>.complete` takes either a `T` or `Future<T>`.
+/// void complete(FutureOr<T> value);
+/// ```
+///
+/// # Advanced
+/// The `FutureOr<int>` type is actually the "type union" of the types `int` and
+/// `Future<int>`. This type union is defined in such a way that
+/// `FutureOr<Object>` is both a super- and sub-type of `Object` (sub-type
+/// because `Object` is one of the types of the union, super-type because
+/// `Object` is a super-type of both of the types of the union). Together it
+/// means that `FutureOr<Object>` is equivalent to `Object`.
+///
+/// As a corollary, `FutureOr<Object>` is equivalent to
+/// `FutureOr<FutureOr<Object>>`, `FutureOr<Future<Object>> is equivalent to
+/// `Future<Object>`.
+abstract class FutureOr<T> {
+  // Private constructor, so that it is not subclassable, mixable, or

[Lasse Reichstein Nielsen, 2016/12/08 16:46:52]

Silly me, I forgot that a factory constructor doesn't actually prevent being
used as a mixin any more. :(
So it's probably better to drop the "factory" again, but keep the throwing.

[floitsch, 2016/12/09 18:19:48]

Done.

+  // instantiable.
+  factory FutureOr._() {
+    throw new UnsupportedError("FutureOr can't be instantiated");
+  }
+}
+
 /**
  * An object representing a delayed computation.
  *
  * A [Future] is used to represent a potential value, or error,
  * that will be available at some time in the future.
  * Receivers of a [Future] can register callbacks
  * that handle the value or error once it is available.
  * For example:
  *
  *     Future<int> future = getFuture();
@@ skipping 763 matching lines @@
   if (replacement != null) {
     error = _nonNullError(replacement.error);
     stackTrace = replacement.stackTrace;
   }
   result._completeError(error, stackTrace);
 }
 
 /** Helper function that converts `null` to a [NullThrownError]. */
 Object _nonNullError(Object error) =>
   (error != null) ? error : new NullThrownError();