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;
 
+/// The union of `Future<T>` and `T`.

[Lasse Reichstein Nielsen, 2016/12/08 15:14:00]

I would save the "union" word to the advanced section. 
Maybe just:
"A type representing either a `Future<T>` or a `T`."

[floitsch, 2016/12/08 16:23:59]

That wording doesn't work for me. If read the wrong way, it can only represent
either or, but not both at the same time.

Changed to `A type representing values that are either `Future<T>` or `T`.

+///
+/// This is a magic class that is recognized by the Dart tools. It is

[Lasse Reichstein Nielsen, 2016/12/08 15:14:00]

I wouldn't actually use the word "magic" in writing.
Maybe something like:

This class declaration represents the actual generic `FutureOr` type, 
which isn't itself a class type. Dart tools will treat references to this
`FutureOr` class as denoting the corresponding actual future-or-value type.

[floitsch, 2016/12/08 16:23:59]

Changed. PTAL.

+/// used in places where functions accept or return a `Future<T>` or a `T`.
+///
+/// This class can not be implemented or extended.

[Lasse Reichstein Nielsen, 2016/12/08 15:14:00]

or mixed in.

The spec language is (e.g.):
so maybe something like:

[Brian Wilkerson, 2016/12/08 15:25:46]

nit: "can not" --> "cannot"
nit: or mixed in? (maybe "implemented" implies that; I usually make both
"extended" and "mixed in" explicit for clarity)

[floitsch, 2016/12/08 16:23:59]

Done.

+///
+/// 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
+/// Since `FutureOr<Object>` is the union of `Future<Object>` and `Object`, it

[Lasse Reichstein Nielsen, 2016/12/08 15:14:00]

"the union" isn't defined anywhere, so it's not clear what it means.
Maybe:

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`.

[floitsch, 2016/12/08 16:23:59]

Done.

+/// is equivalent to `Object`, because `Future<Object>` is a subtype of
+/// `Object`.
+///
+/// As a corollary, `FutureOr<Object>` is equivalent to
+/// `FutureOr<FutureOr<Object>>`.

[Lasse Reichstein Nielsen, 2016/12/08 15:14:00]

(and equivalent to Object)

The more interesting example is:
  FutureOr<Future<Object>> == Future<Object>

[floitsch, 2016/12/08 16:23:59]

Done.

+class FutureOr<T> {
+  // Private constructor, so that it is not subclassable and instantiable.

[Lasse Reichstein Nielsen, 2016/12/08 15:14:00]

or mixin'able, as if that was a word.

For even more breakage for anyone trying to use the class, you can make it a
factory constructor which throws (no generative constructor at all), and make
the class abstract. Still doesn't block the interface.

[floitsch, 2016/12/08 16:23:59]

Done.

+  FutureOr._();
+}
+
 /**
  * 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();