Add support for lazy transformers.

pkg/barback/lib/src/asset_node.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_node;
 
 import 'dart:async';
 
 import 'asset.dart';
 import 'asset_id.dart';
@@ skipping 32 matching lines @@
   /// The current state of the asset node.
   AssetState get state => _state;
   AssetState _state;
 
   /// The concrete asset that this node represents.
   ///
   /// This is null unless [state] is [AssetState.AVAILABLE].
   Asset get asset => _asset;
   Asset _asset;
 
+  /// The callback to be called to notify this asset node's creator that the
+  /// asset should be materialized.
+  ///
+  /// This is only non-null for lazy asset nodes (see

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

"only non-null for lazy" -> "null for non-lazy"

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

Done.

+  /// [AssetNodeController.lazy]). Once this is called, it's set to null and
+  /// [this] is no longer considered lazy.
+  Function _lazyCallback;

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

I'm all for using callbacks in barback, but isn't this inconsistent with the
rest of barback which uses streams? Shouldn't this be a onMaterialize stream?

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

I chose a callback instead because it's guaranteed to only fire once, and the
person who instantiates a lazy node or makes a node lazy should always register
a callback for it.

I'd make this a Future if that worked with synchronous callbacks and I could
somehow return a Future from [AssetNodeController.lazy].

+
   /// A broadcast stream that emits an event whenever the node changes state.
   ///
   /// This stream is synchronous to ensure that when a source asset is modified
   /// or removed, the appropriate portion of the asset graph is dirtied before
   /// any [Barback.getAssetById] calls emit newly-incorrect values.
   Stream<AssetState> get onStateChange => _stateChangeController.stream;
 
   /// This is synchronous so that a source being updated will always be
   /// propagated through the build graph before anything that depends on it is
   /// requested.
@@ skipping 67 matching lines @@
     return onStateChange.firstWhere(test).then((_) => callback(state));
   }
 
   AssetNode._(this.id, this._transform, this._origin)
       : _state = AssetState.DIRTY;
 
   AssetNode._available(Asset asset, this._transform, this._origin)
       : id = asset.id,
         _asset = asset,
         _state = AssetState.AVAILABLE;
+
+  AssetNode._lazy(this.id, this._transform, this._origin, this._lazyCallback)
+      : _state = AssetState.DIRTY;
+
+  /// If [this] is lazy, materialize it; otherwise, do nothing.
+  ///
+  /// See [AssetNodeController.lazy].
+  void materialize() {
+    if (_origin != null) {
+      _origin.materialize();
+    } else if (_lazyCallback != null) {
+      _lazyCallback();
+      _lazyCallback = null;
+    }
+  }
 }
 
 /// The controller for an [AssetNode].
 ///
 /// This controls which state the node is in.
 class AssetNodeController {
   final AssetNode node;
 
   /// Creates a controller for a dirty node.
   AssetNodeController(AssetId id, [TransformNode transform])
       : node = new AssetNode._(id, transform, null);
 
   /// Creates a controller for an available node with the given concrete
   /// [asset].
   AssetNodeController.available(Asset asset, [TransformNode transform])
       : node = new AssetNode._available(asset, transform, null);
 
+  /// Creates a controller for a lazy node.
+  ///
+  /// For the most party, this node works like any other dirty node. However,

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

I'm always trying to maximize my party too, but here it should just be "for the
most part".

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

Done.

+  /// the owner of its controller isn't expected to do the work to make it
+  /// available as soon as possible like they would for a non-lazy node.

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

they -> it

TransformNodes are gender-less, not gender-neutral. :)

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

"They" actually refers to "the owner" here, who is gender-neutral.

+  /// Instead, when its value is needed, [callback] will fire to indicate that
+  /// it should be made available as soon as possible.
+  ///
+  /// [callback] is guaranteed to only fire once.
+  AssetNodeController.lazy(AssetId id, void callback(),
+          [TransformNode transform])
+      : node = new AssetNode._lazy(id, transform, null, callback);
+
   /// Creates a controller for a node whose initial state matches the current
   /// state of [node].
   ///
   /// [AssetNode.origin] of the returned node will automatically be set to
   /// `node.origin`.
+  ///
+  /// If [node] is lazy, the returned node will also be lazy. If the returned
+  /// node is materialized, [node] will be materialized as well.
   AssetNodeController.from(AssetNode node)
       : node = new AssetNode._(node.id, node.transform, node.origin) {
     if (node.state.isAvailable) {
       setAvailable(node.asset);
     } else if (node.state.isRemoved) {
       setRemoved();
     }
   }
 
   /// Marks the node as [AssetState.DIRTY].
   void setDirty() {
     assert(node._state != AssetState.REMOVED);
     node._state = AssetState.DIRTY;
     node._asset = null;
+    node._lazyCallback = null;
     node._stateChangeController.add(AssetState.DIRTY);
   }
 
   /// Marks the node as [AssetState.REMOVED].
   ///
   /// Once a node is marked as removed, it can't be marked as any other state.
   /// If a new asset is created with the same id, it will get a new node.
   void setRemoved() {
     assert(node._state != AssetState.REMOVED);
     node._state = AssetState.REMOVED;
     node._asset = null;
+    node._lazyCallback = null;
     node._stateChangeController.add(AssetState.REMOVED);
   }
 
   /// Marks the node as [AssetState.AVAILABLE] with the given concrete [asset].
   ///
   /// It's an error to mark an already-available node as available. It should be
   /// marked as dirty first.
   void setAvailable(Asset asset) {
     assert(asset.id == node.id);
     assert(node._state != AssetState.REMOVED);
     assert(node._state != AssetState.AVAILABLE);
     node._state = AssetState.AVAILABLE;
     node._asset = asset;
+    node._lazyCallback = null;
     node._stateChangeController.add(AssetState.AVAILABLE);
   }
+
+  /// Marks the node as [AssetState.DIRTY] and lazy.
+  ///
+  /// Lazy nodes aren't expected to have their values generated until it's

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

"it's necessary" -> "needed".

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

Done.

+  /// necessary. Once it's necessary, [callback] will be called. [callback] is
+  /// guaranteed to be called only once.
+  ///
+  /// See also [AssetNodeController.lazy].
+  void setLazy(void callback()) {
+    assert(node._state != AssetState.REMOVED);
+    node._state = AssetState.DIRTY;
+    node._asset = null;
+    node._lazyCallback = callback;
+    node._stateChangeController.add(AssetState.DIRTY);
+  }
 }
 
 // TODO(nweiz): add an error state.
 /// An enum of states that an [AssetNode] can be in.
 class AssetState {
   /// The node has a concrete asset loaded, available, and up-to-date. The asset
   /// is accessible via [AssetNode.asset]. An asset can only be marked available
   /// again from the [AssetState.DIRTY] state.
   static final AVAILABLE = const AssetState._("available");
 
@@ skipping 13 matching lines @@
 
   /// Whether this state is [AssetState.DIRTY].
   bool get isDirty => this == AssetState.DIRTY;
 
   final String name;
 
   const AssetState._(this.name);
 
   String toString() => name;
 }