dart:io | Ensure that close() returns a Future<this> on all (Raw)?(Secure)?(Server)?Socket classes …

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 [Future] represents a delayed computation. It is used to obtain a not-yet
  * available value, or error, sometime in the future.  Receivers of a
  * [Future] can register callbacks that handle the value or error once it is
@@ skipping 304 matching lines @@
   Future<T> whenComplete(action());
 
   /**
    * Creates a [Stream] that sends [this]' completion value, data or error, to
    * its subscribers. The stream closes after the completion value.
    */
   Stream<T> asStream();
 }
 
 /**
- * A [Completer] is used to produce [Future]s and supply their value when it
- * becomes available.
+ * A [Completer] is used to produce [Future]s and to complete those futures
+ * with a value or error at a later time.
  *
- * A service that provides values to callers, and wants to return [Future]s can
- * use a [Completer] as follows:
+ * A class that wants to return [Future]s can use a [Completer] as follows:
  *
- *     Completer completer = new Completer();
- *     // send future object back to client...
- *     return completer.future;
- *     ...
+ *     Class myAsyncOperation {
+ *       Completer _completer = new Completer();
  *
- *     // later when value is available, call:
- *     completer.complete(value);
+ *       Future<T> myOp() {
+ *         _startOperation();
+ *         // send future object back to client...
+ *         return _completer.future;
+ *       }
  *
- *     // alternatively, if the service cannot produce the value, it
- *     // can provide an error:
- *     completer.completeError(error);
+ *       // Something calls this when the value is ready.
+ *       _finishOperation(T result) {
+ *         _completer.complete(value);
+ *       }
+ *
+ *       // If something goes wrong, call this.
+ *       _errorHappened(error) {
+ *         _completer.completeError(error);
+ *       }
+ *     }
  *
  */
 abstract class Completer<T> {
 
+  /**
+   * Creates a completer whose future is completed asynchronously, sometime
+   * after [complete] is called on it. This allows a call to [complete] to
+   * be in the middle of other code, without running an unknown amount of
+   * future completion and [then] callbacks synchronously at the point that
+   * [complete] is called.
+   *
+   * Example:
+   *
+   *     var completer = new Completer.sync();
+   *     completer.future.then((_) { bar(); });
+   *     // The completion is the result of the asynchronous onDone event.
+   *     // However, there is code executed after the call to complete,
+   *     // but before completer.future runs its completion callback.
+   *     stream.listen(print, onDone: () {
+   *       completer.complete("done");
+   *       foo();  // In this case, foo() runs before bar().
+   *     });
+   */
   factory Completer() => new _AsyncCompleter<T>();
 
   /**
    * Completes the future synchronously.
    *
    * This constructor should be avoided unless the completion of the future is
    * known to be the final result of another asynchronous operation. If in doubt
    * use the default [Completer] constructor.
    *
    * Example:
    *
    *     var completer = new Completer.sync();
    *     // The completion is the result of the asynchronous onDone event.
    *     // No other operation is performed after the completion. It is safe
    *     // to use the Completer.sync constructor.
    *     stream.listen(print, onDone: () { completer.complete("done"); });
    *
    * Bad example. Do not use this code. Only for illustrative purposes:
    *
    *     var completer = new Completer.sync();
+   *     completer.future.then((_) { bar(); });
    *     // The completion is the result of the asynchronous onDone event.
    *     // However, there is still code executed after the completion. This
    *     // operation is *not* safe.
    *     stream.listen(print, onDone: () {
    *       completer.complete("done");
-   *       foo();  // This operation follows the completion.
+   *       foo();  // In this case, foo() runs after bar().
    *     });
-   *
-   * *WARNING* This constructor is experimental and could disappear or change
-   * behavior.
    */
   factory Completer.sync() => new _SyncCompleter<T>();
 
   /** The future that will contain the result provided to this completer. */
   Future get future;
 
   /**
    * Completes [future] with the supplied values.
    *
    * All listeners on the future will be immediately informed about the value.
    */
   void complete([T value]);
 
   /**
    * Complete [future] with an error.
    *
    * Completing a future with an error indicates that an exception was thrown
    * while trying to produce a value.
    *
    * The argument [exception] should not be `null`.
    */
   void completeError(Object exception, [Object stackTrace]);
 
   /**
    * Whether the future has been completed.
    */
   bool get isCompleted;
 }