Serialize barback assets more efficiently.

pkg/barback/lib/src/internal_asset.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.asset;
+library barback.internal_asset;
 
 import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
+import 'asset.dart';
 import 'asset_id.dart';
 import 'file_pool.dart';
+import 'serialize.dart';
 import 'stream_replayer.dart';
 import 'utils.dart';
 
-/// A blob of content.
+/// The internal base class of barback assets.
 ///
-/// Assets may come from the file system, or as the output of a [Transformer].
-/// They are identified by [AssetId].
-abstract class Asset {
-  /// The ID for this asset.
+/// This exposes serialization infrastructure so that pub can use it without
+/// making it part of the public barback API.
+abstract class InternalAsset implements Asset {
   final AssetId id;
 
-  Asset(this.id);
+  InternalAsset(this.id);
 
-  factory Asset.fromBytes(AssetId id, List<int> bytes) =>
-      new _BinaryAsset(id, bytes);
+  /// Deserialize an asset that's been serialized using [serialize].
+  factory InternalAsset.deserialize(Map asset) {
+    switch (asset['type']) {
+      case 'stream': return new StreamAsset.deserialize(asset);
+      case 'binary': return new BinaryAsset.deserialize(asset);
+      case 'file': return new FileAsset.deserialize(asset);
+      case 'string': return new StringAsset.deserialize(asset);
+      default:
+        throw new FormatException('Unknown asset type "${asset['type']}".');
+    }
+  }

[Bob Nystrom, 2013/11/06 21:29:08]

How about just moving this to Asset and getting rid of this class?

[nweiz, 2013/11/07 00:44:48]

I really didn't want to commit to a publicly-visible serialization API before we
have a good solution for custom asset subclasses. Especially if we're going to
try to bring barback to 1.0 soon, I don't want us to decide to go a different
direction to support more general serialization and then have to go on supporint
[Asset.serialize] until 2.0 because someone could theoretically be using it.

[Bob Nystrom, 2013/11/07 18:04:56]

We could put it in a separate library (lib/serialization.dart). Given that
barback is still <1.0, we aren't committed to any API. I'm definitely not
excited about committing to exposing InternalAsset and the other concrete asset
classes in the public API.
My hunch is that we won't hit 1.0 soon. I think we'll be doing some non-trivial
performance work that will likely impact the public API and that stuff will take
a while to settle down. (Stuff we've talked about like being able to ask a
transformer if it *may* generate an asset, etc.)

[nweiz, 2013/11/07 22:36:08]

"lib/serialization.dart" would still be part of the public API. Anything not in
"src" is part of the public API. The only way to avoid exposing these is to keep
them in "src".
Even so, we shouldn't add a public API that no external users want and that we
anticipate will change in the future.

 
-  factory Asset.fromFile(AssetId id, File file) =>
-      new _FileAsset(id, file);
-
-  factory Asset.fromString(AssetId id, String content) =>
-      new _StringAsset(id, content);
-
-  factory Asset.fromPath(AssetId id, String path) =>
-      new _FileAsset(id, new File(path));
-
-  /// Creates an asset from a stream.
-  ///
-  /// This immediately starts draining [stream].
-  factory Asset.fromStream(AssetId id, Stream<List<int>> stream) =>
-      new _StreamAsset(id, stream);
-
-  /// Returns the contents of the asset as a string.
-  ///
-  /// If the asset was created from a [String] the original string is always
-  /// returned and [encoding] is ignored. Otherwise, the binary data of the
-  /// asset is decoded using [encoding], which defaults to [UTF8].
-  Future<String> readAsString({Encoding encoding});
-
-  /// Streams the binary contents of the asset.
-  ///
-  /// If the asset was created from a [String], this returns its UTF-8 encoding.
-  Stream<List<int>> read();
+  /// Serialize this asset to a map that can be sent between isolates.
+  Map serialize();
 }
 
 /// An asset whose data is stored in a list of bytes.
-class _BinaryAsset extends Asset {
+class BinaryAsset extends InternalAsset {
   final List<int> _contents;
 
-  _BinaryAsset(AssetId id, this._contents)
+  BinaryAsset(AssetId id, this._contents)
       : super(id);
 
+  BinaryAsset.deserialize(Map asset)
+      : this(deserializeId(asset['id']), asset['contents']);
+
   Future<String> readAsString({Encoding encoding}) {
     if (encoding == null) encoding = UTF8;
 
     return new Future.value(encoding.decode(_contents));
   }
 
   Stream<List<int>> read() => new Future<List<int>>.value(_contents).asStream();
 
   String toString() {
     var buffer = new StringBuffer();
@@ skipping 15 matching lines @@
     } else {
       for (var i = 0; i < _contents.length; i++) {
         if (i > 0) buffer.write(" ");
         buffer.write(byteToHex(_contents[i]));
       }
     }
 
     buffer.write("]");
     return buffer.toString();
   }
+
+  Map serialize() {
+    // TODO(nweiz): Send a typed array if that works after issue 14703 is fixed.
+    return {
+      'type': 'binary',
+      'id': serializeId(id),
+      'contents': _contents.toList()

[Bob Nystrom, 2013/11/06 21:29:08]

Why copy the list? It's immutable (or, at least, it should be).

[nweiz, 2013/11/07 00:44:48]

The user could pass anything that implements List<int>, but only dart:core lists
are actually serializable.

[Bob Nystrom, 2013/11/07 18:04:56]

Ah, makes sense. Leave a comment to that effect.

This may be a perf hit. Maybe add a TODO to see if we can avoid the copy in some
cases?

[nweiz, 2013/11/07 22:36:08]

Done.
I've just gone ahead and added a [runtimeType] check.

+    };
+  }
 }
 
 /// An asset backed by a file on the local file system.
-class _FileAsset extends Asset {
+class FileAsset extends InternalAsset {
   /// Use a [FilePool] to handle reads so we can try to cope with running out
   /// of file descriptors more gracefully.
   static final _pool = new FilePool();
 
-  final File _file;
-  _FileAsset(AssetId id, this._file)
+  final String _path;
+  FileAsset(AssetId id, this._path)
       : super(id);
 
+  FileAsset.deserialize(Map asset)
+      : this(deserializeId(asset['id']), asset['path']);
+
   Future<String> readAsString({Encoding encoding}) {
     if (encoding == null) encoding = UTF8;
-    return _pool.readAsString(_file, encoding);
+    return _pool.readAsString(_path, encoding);
   }
 
-  Stream<List<int>> read() => _pool.openRead(_file);
+  Stream<List<int>> read() => _pool.openRead(_path);
 
-  String toString() => 'File "${_file.path}"';
+  String toString() => 'File "${_path}"';
+
+  Map serialize() {
+    return {
+      'type': 'file',
+      'id': serializeId(id),
+      'path': _path
+    };
+  }
 }
 
 /// An asset whose data is stored in a string.
-class _StringAsset extends Asset {
+class StringAsset extends InternalAsset {
   final String _contents;
 
-  _StringAsset(AssetId id, this._contents)
+  StringAsset(AssetId id, this._contents)
       : super(id);
 
+  StringAsset.deserialize(Map asset)
+      : this(deserializeId(asset['id']), asset['contents']);
+
   Future<String> readAsString({Encoding encoding}) =>
       new Future.value(_contents);
 
   Stream<List<int>> read() =>
       new Future<List<int>>.value(UTF8.encode(_contents)).asStream();
 
   String toString() {
     // Don't show the whole string if it's long.
     var contents = _contents;
     if (contents.length > 40) {
       contents = contents.substring(0, 20) + " ... " +
                  contents.substring(contents.length - 20);
     }
 
     contents = _escape(contents);
     return 'String "$contents"';
   }
 
   String _escape(String string) {
     return string
         .replaceAll("\"", r'\"')
         .replaceAll("\n", r"\n")
         .replaceAll("\r", r"\r")
         .replaceAll("\t", r"\t");
   }
+
+  Map serialize() {
+    return {
+      'type': 'string',
+      'id': serializeId(id),
+      'contents': _contents
+    };
+  }
 }
 
 /// An asset whose data is available from a stream.
-class _StreamAsset extends Asset {
+class StreamAsset extends InternalAsset {
   /// A stream replayer that records and replays the contents of the input
   /// stream.
   final StreamReplayer<List<int>> _replayer;
 
-  _StreamAsset(AssetId id, Stream<List<int>> stream)
+  StreamAsset(AssetId id, Stream<List<int>> stream)
       : _replayer = new StreamReplayer(stream),
         super(id);
 
+  StreamAsset.deserialize(Map asset)
+      : this(deserializeId(asset['id']), deserializeStream(asset['stream']));
+
   Future<String> readAsString({Encoding encoding}) {
     if (encoding == null) encoding = UTF8;
     return _replayer.getReplay().toList()
         .then((chunks) => encoding.decode(flatten(chunks)));
   }
 
   Stream<List<int>> read() => _replayer.getReplay();
 
   String toString() => "Stream";
+
+  Map serialize() {
+    return {
+      'type': 'stream',
+      'id': serializeId(id),
+      'stream': serializeStream(_replayer.getReplay())
+    };
+  }
 }