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

sdk/lib/async/future.dart

Index: sdk/lib/async/future.dart
diff --git a/sdk/lib/async/future.dart b/sdk/lib/async/future.dart
index 7d892c687ef1cd0197b149b65a173d56dcc6f3a5..428113f0819f8fde0e8c6bceeed7ed4d607faba9 100644
--- a/sdk/lib/async/future.dart
+++ b/sdk/lib/async/future.dart
@@ -4,6 +4,46 @@
 
 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.
  *