Add support for lazy transformers.

pkg/barback/lib/src/serialize.dart

Index: pkg/barback/lib/src/serialize.dart
diff --git a/pkg/barback/lib/src/serialize.dart b/pkg/barback/lib/src/serialize.dart
index 7114039e44d5cc417baf8dfc62a97400619447c3..4d3f973f2a313b097c9f2806d8fda22efff6e992 100644
--- a/pkg/barback/lib/src/serialize.dart
+++ b/pkg/barback/lib/src/serialize.dart
@@ -33,6 +33,44 @@ SendPort serializeStream(Stream stream) {
   return receivePort.sendPort;
 }
 
+/// Converts [callback] into a [SendPort] which which another isolate can call

[Bob Nystrom, 2014/01/30 19:33:44]

I think you had something similar in the previous lazy patch. In both cases, the
behavior of these is really confusing and could use more documentation.
Something like:

"Returns a new SendPort. When a second SendPort is sent through that one, the
callback will be invoked and its result sent to *that* SendPort."

Or something along those lines. This does make we wonder if there's a simpler
way to do this?

[nweiz, 2014/01/31 03:43:27]

I don't like how this description exposes the implementation details of these
functions. From the user's perspective, [serializeCallback] returns a black box
that can be passed between isolates and deserialized to a callback via
[deserializeCallback].
These are actually no longer used, now that LazyAsset doesn't exist anymore.
I'll stash them for now.

I'm pretty sure this is the least complicated way to do this sort of thing,
though. The only way to send a push notification across isolates is by sending a
SendPort. Due to the lack of any sort of auto-serialization, this is as close as
we can come to wrapping this logic in a nicer API.

[Bob Nystrom, 2014/01/31 18:28:53]

I'm OK with that too, but in that case, I wouldn't annotate the return type as
SendPort. That makes the opacity explicit.
SGTM.

+/// [callback].
+///
+/// [callback] may return either a serializable value or a [Future] of a
+/// serializable value.
+SendPort serializeCallback(callback()) {
+  var receivePort = new ReceivePort();
+  receivePort.first.then(
+      (sendPort) => _sendFuture(syncFuture(callback), sendPort));
+  return receivePort.sendPort;
+}
+
+/// Converts [future] into a [SendPort] which which another isolate can listen
+/// to the value of [Future].

[Bob Nystrom, 2014/01/30 19:33:44]

Ditto above comment.

[nweiz, 2014/01/31 03:43:27]

N/A

+///
+/// [Future] must produce a serializable value.
+SendPort serializeFuture(Future future) {
+  // Ensure the future doesn't top-level an error that arrives before
+  // [receivePort] fires.
+  future.catchError(null);

[Bob Nystrom, 2014/01/30 19:33:44]

I don't understand how passing a null catch handler accomplishes this. I'd
expect this to be a misuse of the Future API. What am I missing here?

[nweiz, 2014/01/31 03:43:27]

"null" means approximately the same thing as "() {}" to dart:async. They pass
null to futures all over the place in their code, so I assumed it was kosher
externally, too.

[Bob Nystrom, 2014/01/31 18:28:53]

Oh, wow. That's totally news to me. They certainly don't document that. I would
expect adding null to mean "no handler", which would then top level an error.

I'd more comfortable if we used an explicit no-op fn here.

+
+  var receivePort = new ReceivePort();
+  receivePort.first.then((sendPort) => _sendFuture(future, sendPort));
+  return receivePort.sendPort;
+}
+
+/// A helper method for sending the result of [future] across [sendPort].

[Bob Nystrom, 2014/01/30 19:33:44]

"helper method" doesn't add much. How about "Sends the result of [future] to
[sendPort] when it completes."

[nweiz, 2014/01/31 03:43:27]

N/A

+void _sendFuture(Future future, SendPort sendPort) {
+  future.then((value) {
+    sendPort.send({'type': 'success', 'value': value});
+  }, onError: (error, stackTrace) {
+    sendPort.send({
+      'type': 'error',
+      'error': CrossIsolateException.serialize(error, stackTrace)
+    });
+  });
+}
+
 /// Converts a serializable map into an [AssetId].
 AssetId deserializeId(Map id) => new AssetId(id['package'], id['path']);
 
@@ -52,6 +90,34 @@ Stream deserializeStream(SendPort sendPort) {
   });
 }
 
+/// A function that takes no arguments and returns a future.
+typedef Future AsyncFunction();
+
+/// Converts a [SendPort] that was created using [serializeCallback] to a
+/// callback that returns a [Future].
+///
+/// If [deserialize] is passed, the return value of the callback is passed
+/// through it before being returned.
+AsyncFunction deserializeCallback(SendPort sendPort, [deserialize(value)]) {
+  return () {

[Bob Nystrom, 2014/01/30 19:33:44]

What's the outer function wrapper for?

+    return deserializeFuture(sendPort).then((value) {
+      return deserialize == null ? value : deserialize(value);
+    });
+  };
+}
+
+/// Converts a [SendPort] that was created using [serializeFuture] to a
+/// [Future].
+Future deserializeFuture(SendPort sendPort) {
+  var receivePort = new ReceivePort();
+  sendPort.send(receivePort.sendPort);
+  return receivePort.first.then((response) {
+    if (response['type'] == 'success') return response['value'];
+    var exception = new CrossIsolateException.deserialize(response['error']);
+    return new Future.error(exception, exception.stackTrace);
+  });
+}
+
 /// The body of a [StreamTransformer] that deserializes the values in a stream
 /// sent by [serializeStream].
 StreamSubscription _deserializeTransformer(Stream input, bool cancelOnError) {