Deprecate the dart:cli library and waitFor method.

Change-Id: Ia7af0febf17b310de9561eca254f1bd9add079ac
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/210125
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>
Reviewed-by: Michael Thomsen <mit@google.com>
Reviewed-by: Nate Bosch <nbosch@google.com>

CHANGELOG.md

@@ -57,6 +57,11 @@
 - Added `void unawaited(Future)` top-level function to deal with the
   `unawaited_futures` lint.
 
+#### `dart:cli`
+
+- The experimental `waitFor` functionality, and the library containing only that
+  function, are now deprecated.
+
 #### `dart:core`
 
 - Introduce `Enum` interface implemented by all `enum` declarations.

sdk/lib/cli/cli.dart

@@ -4,6 +4,8 @@
 
 /// {@category VM}
 /// {@nodoc}
+@Deprecated(
+    "The functionality of this library is incomplete and may be removed in a later version")
 library dart.cli;
 
 import 'dart:async';

sdk/lib/cli/wait_for.dart

@@ -111,7 +111,33 @@ class _WaitForUtils {
  * Please be aware that nesting calls to [waitFor] can lead to deadlock if
  * subsequent calls block waiting for a condition that is only satisfied when
  * an earlier call returns.
+ *
+ * **NOTICE**
+ * The `waitFor` feature is deprecated.
+ * The feature was intended to solve a particular problem for existing code,
+ * a problem introduced by a breaking change to the platform libraries.
+ * The `waitFor` function is not suitable for general use.
+ * The feature has shortcomings that can affect other code
+ * running in the same isolate, including:
+ *  * A function call that looks synchronous may cause other asynchronous
+ *    events to run before it returns.
+ *    This is something synchronous code can usually assume not to happen,
+ *    and some code may have been written to take advantage of that
+ *    assumed behavior. Such code can fail in unexpected ways.
+ *  * Multiple nested calls to `waitFor` may block each other
+ *    since the most recent call always needs to complete
+ *    before any other call can complete.
+ *    Judicious use of `waitFor` is necessary to avoid unexpected deadlocks
+ *    which wouldn't happen if using `await` instead.
+ *    If more than one library in the same program is using `waitFor`,
+ *    then it's hard to avoid or control whether such blocking will happen.
+ *
+ * The feature is not actively maintained.
+ * It will remain as-is to support the original problem it was added to solve,
+ * at least until that problem can be solved in some other way.
  */
+@Deprecated(
+    "This functionality is incomplete and may be removed in a later version")
 T waitFor<T>(Future<T> future, {Duration? timeout}) {
   late T result;
   bool futureCompleted = false;