Add an AsyncThunk class.

lib/src/async_thunk.dart

Index: lib/src/async_thunk.dart
diff --git a/lib/src/async_thunk.dart b/lib/src/async_thunk.dart
new file mode 100644
index 0000000000000000000000000000000000000000..97c48f3fb78a78b131c5487b1c8cb3da474d32be
--- /dev/null
+++ b/lib/src/async_thunk.dart
@@ -0,0 +1,46 @@
+// 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_thunk;
+
+import 'dart:async';
+
+/// A class for running an asynchronous method body exactly once and caching its
+/// result.
+///
+/// This should be stored as an instance variable, and [run] should be 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
+/// class SomeResource {
+///   final _closeThunk = new AsyncThunk();
+///
+///   Future close() {
+///     return _closeThunk.run(() {
+///       // ...
+///     });
+///   }
+/// }
+/// ```
+class AsyncThunk<T> {

[Lasse Reichstein Nielsen, 2015/07/02 12:25:58]

The "Thunk" name doesn't match what I normally think of as a "thunk": A nullary
function passed as a paremeter to something else.
The "fn" function is a thunk, but this class doesn't really match.

No good idea for a better name, "AsyncRunOnce" is not a great name.
"AsyncResultCache"?

[nweiz, 2015/07/06 21:04:16]

The idea was to evoke the lazy-evaluation language use of memoized thunks; this
has the same "run once then save the value" behavior.

I'm okay with changing it to AsyncResultCache, though.

[Lasse Reichstein Nielsen, 2015/07/07 09:32:40]

I thought so, and it might be possible to put the Thunk into the name, but the
class is the memoizer, not the thunk.
AsyncThunkMemoizer?

[nweiz, 2015/07/07 21:46:31]

Changed to AsyncMemoizer.

+  /// 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.
+  ///
+  /// If [run] has already been called, this returns the original result.
+  Future<T> run(fn()) {

[Lasse Reichstein Nielsen, 2015/07/02 12:25:58]

Do you actually expect the run function to be called more than once?
Is it called with different arguments? If so, it seems unsafe to not run the
functions. If not, maybe pass the function to the constructor instead of passing
it to each run call (it's slightly misleading to be able to pass different
functions with each call if only the first call matters).

That would mean you have a delayed future completer!

You provide a function to run when you create the DelayedFutureCompleter, but
delay running it until later. You can't change your mind about what to complete
with. So, signture:

 class DelayedCompleter<T> {
   Future<T> get future;
   DelayedCompleter(T computation());
   // Can be run more than once, starts computation the first time it's
   // run, completes [future] when computation finishes.
   void start();  // or "run".
 }

(Maybe even add "set computation(T computation())" that can't be used after
calling start).

I think that would be better as an abstraction than the current class.

[nweiz, 2015/07/06 21:04:16]

That would work well with slightly different language semantics, but Dart's
restrictions on instance variable initializers make that much uglier to use in
practice. I really want the body of the cached method to be in the same place as
the declaration, and that's not possible if the body has to be defined when the
cache is initialized, since the initialization would have to be done in the
constructor.

[Lasse Reichstein Nielsen, 2015/07/07 09:32:40]

So you only expect the "run" function to be called from one place. Nothing
prevents calling it from different locations with different thunks, but we can
at least discourage it by saying that it won't work anyway.

I still think it's misleading to call "run(thunk)" and it doesn't actually run.

So, how about some slight renamings and modifications? :)

class ThunkMemoizer<T> {
  Future<T> _result;
  /// Call to return the result of calling [thunk].
  /// 
  /// Only the first call to [runOnce] does anything, 
  /// further calls return the same result as the first call.
  /// Calling with a different [thunk] on later calls will not
  /// make any difference, the intended use is to only call the
  /// the `runOnce` function from one location and always with the
  /// same (or equivalent) function as argument.
  Future<T> runOnce(T thunk()) {
    if (_result == null) _result = new Future<T>.sync(thunk);
    return _result;
  }
}

With a little luck the runOnce will be inlined at the call point, and the thunk
won't even be created on the second run.

By making the call return the Future instead of having it on the side, you avoid
having to consider whether you can read [future] before calling [run].

It seems like a slightly more general design.

[nweiz, 2015/07/07 21:46:31]

Done.

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