Add an AsyncThunk class.

lib/src/async_memoizer.dart

Index: lib/src/async_memoizer.dart
diff --git a/lib/src/async_memoizer.dart b/lib/src/async_memoizer.dart
new file mode 100644
index 0000000000000000000000000000000000000000..d464760296518a120ca068943f4ed0bb75988219
--- /dev/null
+++ b/lib/src/async_memoizer.dart
@@ -0,0 +1,45 @@
+// Copyright (c) 2015, 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.
+
+library async.async_memoizer;
+
+import 'dart:async';
+
+/// A class for running an asynchronous method body exactly once and caching its

[Lasse Reichstein Nielsen, 2015/07/08 07:37:34]

method body -> function

[nweiz, 2015/07/09 00:45:13]

Done.

+/// result.
+///
+/// This should be stored as an instance variable, and [runOnce] should be

[Lasse Reichstein Nielsen, 2015/07/08 07:37:34]

Drop the usage of "this", or at least don't make it "should". You can also use
it as a local variable and use it from, say, a callback function on a stream.
I don't understand the rest of the sentence.

What is consistent is that you create one memoizer, then call it from some code
that will run more than once.

How about:

An `AsyncMemoizer` is used when some function may be run multiple times in order
to get its result, but it only actually needs to be run once for its effect.
To memoize the result of an async function, you can create a memoizer outside
the function (for example as an instance field if you want to memoize the result
of a method), and then wrap the function's body in a call to [runOnce].

Example:
```dart
  ... your example ...
```

[nweiz, 2015/07/09 00:45:13]

Done.

+/// called when the method is invoked with the uncached method body. The first
+/// time, it runs the body; after that, it returns the future from the first
+/// run.
+///
+/// This is useful for methods like `close()` and getters that need to do
+/// asynchronous work. For example:
+///
+/// ```dart

[Lasse Reichstein Nielsen, 2015/07/08 07:37:34]

Does DartDoc understand "```dart" now! If so, yey! I'm so tired of indenting by
four!

[nweiz, 2015/07/09 00:45:13]

I think so? I'm not 100% sure, but I'll keep an eye on this and change it if it
breaks.

+/// class SomeResource {
+///   final _closeMemo = new AsyncMemoizer();
+///
+///   Future close() => _closeMemo.runOnce(() {
+///     // ...
+///   });
+/// }
+/// ```
+class AsyncMemoizer<T> {
+  /// The future containing the method's result.
+  ///
+  /// This will be `null` if [run] hasn't been called yet.
+  Future<T> _future;
+
+  /// Whether [run] has been called yet.
+  bool get hasRun => _future != null;
+
+  /// Runs the method body, [fn], if it hasn't been run before.

[Lasse Reichstein Nielsen, 2015/07/08 07:37:34]

method body -> function.

[nweiz, 2015/07/09 00:45:13]

Done.

+  ///
+  /// If [run] has already been called, this returns the original result.
+  Future<T> runOnce(fn()) {

[Lasse Reichstein Nielsen, 2015/07/08 07:37:34]

Rename "fn" to "computation".
This matches the argument to Future.sync and other places where we don't have a
better name for an async function.

[nweiz, 2015/07/09 00:45:13]

Done.

+    if (_future == null) _future = new Future.sync(fn);
+    return _future;
+  }
+}