Add support for lazy transformers.

pkg/barback/lib/src/serialize.dart

 // Copyright (c) 2013, 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 barback.serialize;
 
 import 'dart:async';
 import 'dart:isolate';
 
 import 'package:stack_trace/stack_trace.dart';
@@ skipping 15 matching lines @@
       sendPort.send({
         'type': 'error',
         'error': CrossIsolateException.serialize(error, stackTrace)
       });
     });
   });
 
   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']);
 
 /// Convert a [SendPort] whose opposite is waiting to send us a stream into a
 /// [Stream].
 ///
 /// No stream data will actually be sent across the isolate boundary until
 /// someone subscribes to the returned stream.
 Stream deserializeStream(SendPort sendPort) {
   return callbackStream(() {
     var receivePort = new ReceivePort();
     sendPort.send(receivePort.sendPort);
     // TODO(nweiz): use a const constructor for StreamTransformer when issue
     // 14971 is fixed.
     return receivePort.transform(
         new StreamTransformer(_deserializeTransformer));
   });
 }
 
+/// 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) {
   var subscription;
   var transformed = input.transform(new StreamTransformer.fromHandlers(
       handleData: (data, sink) {
     if (data['type'] == 'data') {
       sink.add(data['data']);
     } else if (data['type'] == 'error') {
       var exception = new CrossIsolateException.deserialize(data['error']);
@@ skipping 52 matching lines @@
 /// A regular expression to match the exception prefix that some exceptions'
 /// [Object.toString] values contain.
 final _exceptionPrefix = new RegExp(r'^([A-Z][a-zA-Z]*)?(Exception|Error): ');
 
 /// Get a string description of an exception.
 ///
 /// Many exceptions include the exception class name at the beginning of their
 /// [toString], so we remove that if it exists.
 String _getErrorMessage(error) =>
   error.toString().replaceFirst(_exceptionPrefix, '');